The Battle for Wesnoth Wiki - User contributions [en]

EventWML

2015-11-05T01:53:00Z

Anonymissimus: /* id */

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

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

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

'''Lexicon side note:''' ''The word "event" in the [event] tag itself may be considered an abbreviation of the word "event handler" because it is technically not a game "event" but an event '''handler''' for the game events fired with the given 'name'. However, this distinction is usually unimportant in most discussions and the event handlers are therefore simply referred to as "events" in this documentation.''

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

Usage:
name=<value>

This key defines which game event or trigger your [event] tag will be handling. This 'name' key should not be confused with a descriptive comment; it is rather a precise value which must match the predefined game event's name to be valid.

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

For example:

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

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

==== Predefined Events Without Filters ====

These events do not take filter parameters (except [filter_condition] which works for all events).

===== preload =====

Triggers before a scenario 'prestarts' and when loading a savegame -- before anything is shown on the screen at all. Can be used to set up the [[LuaWML|Lua]] environment: loading libraries, defining helper functions, etc.

'''Note:''' Unlike prestart and start, the preload event '''must be able to fire more than once!''' This is because it is triggered each time a savegame is loaded in addition to the initial time when it loads before the scenario 'prestart'. This means that it is effectively ''mandatory'' to have the [[#first_time_only|first_time_only=no]] key value in a preload event.

===== prestart =====

Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.

'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

===== start =====

Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.

'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

===== new turn =====

Triggers at the start of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. Before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.

===== turn end =====

Triggers at the end of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. The WML variable '''side_number''' will contain the side that ended their turn.

===== turn ''X'' end =====

Triggers at the end of turn ''X''.

===== side turn =====

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

===== ai turn =====

Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side. Note that this event might be called several times per turn in case that fallbacks to human or droiding is involved. I.e. it happens at the middle of turn of human side 1 if the human player droids his side. It happens after the selection of ai to play the turn but before AI is told that new turn has come.

'''Note:''' ''This event currently breaks replays since it is not explicitly saved in a replay and there is no AI involved in replays...''

===== turn refresh =====

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

Note that the turn refresh event does occur on turn 1, even though healing, income and unit refreshing do not.

===== turn ''X'' =====

Triggers at the start of turn ''X''. It's the first side initialization event.

Side initialization events go in the order of:

# '''turn ''X'''''
# '''new turn'''
# '''side turn'''
# '''side ''X'' turn'''
# '''side turn ''X'''''
# '''side ''X'' turn ''Y'''''
# '''turn refresh'''
# '''side ''X'' turn refresh'''
# '''turn ''X'' refresh'''
# '''side ''X'' turn ''Y'' refresh'''

===== side ''X'' turn ''Y'' =====

This event triggers at the start of turn ''Y'' of side X

===== side ''X'' turn =====

This event triggers at the start of any turn of side X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

===== side turn ''X'' =====

This event triggers at the start of any side on turn X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

===== side X turn Y refresh =====

This event triggers at the turn refresh for side X on turn Y

===== side ''X'' turn refresh =====

This event triggers at the turn refresh for side X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

===== turn ''X'' refresh =====

This event triggers for any side at the refresh of turn X.

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

===== side turn end =====

Triggers after a side ends its turn. Like side turn, there are also some variations for specific combinations of side number and turn number. Here is the order in which the turn end events trigger:

# '''side turn end'''
# '''side ''X'' turn end'''
# '''side turn ''X'' end'''
# '''side ''X'' turn ''Y'' end'''
# '''turn end'''
# '''turn ''X'' end'''

===== time over =====

Triggers on turn ''turns''. (''turns'' is specified in [scenario])

===== enemies defeated =====

Triggers when all sides that are not defeated are allied and if there is at least one human (or human networked) side among them. Especially this event triggers in a situaltion that would normaly cause a victory due to enemies defeated. (regardless of whether this was disabled with victory_when_enemies_defeated=no).

===== 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]]). This event is not synchonized in networked mp or in replays. The reason is that it is possible to have diffrent results in a mp game (one player wins so a '''victory''' event is fired on that client, other player loses so a '''defeat''' event is fired on his client)

===== 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]]). Like '''victory''', this event is not synchonized in networked mp or in replays.

==== Predefined Events With Filters ====

Filters (except [filter_condition] which is for all sorts of events) can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true.
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]. weapon and second_weapon variables are available inside attack, attacker_hits, defender_hits, die and last_breath events. See [[VariablesWML#Automatically_Stored_Variables|automatically stored variables]] for more information.

===== moveto =====

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

===== sighted =====

A '''sighted''' event is triggered by a unit becoming visible to a side (other than the unit's own side). This is mostly useful when the side seeing the unit uses [[fog of war]] or [[shroud]], but they still fire even when fog/shroud is not in use, and they do take into account the {{tag2|AbilitiesWML#The_.5Babilities.5D_tag|hides}} ability (for a moving unit and for ambushers). The ''primary unit'' is the unit that became visible, and the ''secondary unit'' belongs to the side that now sees the primary unit. In some cases, sighted events can be delayed from when they "should" occur. If that happens, the secondary unit will be filtered as if it was at the location where the event "should" have occurred, and ''x2,y2'' will store that location (not the current position of the secondary unit). To understand when sighted events fire, it is helpful to distinguish the times the acting unit sights other units from the times when the acting unit is sighted.

An acting unit can sight other units when it is recruited, recalled, leveled, or moved, and when fog or shroud is cleared from occupied hexes as a result. In these cases, the acting unit is always the ''secondary unit''. For the first three actions, there are two events associated with the action; clearing occurs between these events, but any sighted events are fired after the second event. (For example, when a unit is recruited, the ''prerecruit'' event fires, then fog is cleared, then the ''recruit'' event fires, then ''sighted'' events fire.) For movement, the sighted events fire between ''enter_hex'' and ''exit_hex'' events, but sometimes sighted events are postponed until the moving unit reaches a good place to stop (e.g. not in an occupied hex). As a major exception to the above, players have the option to delay shroud (and fog) updates. If the player delays shroud updates, sighted events are also delayed until the shroud is updated.

An acting unit can be sighted by other sides when it is recruited, recalled, leveled (in rare cases), or moved. In these cases, the acting unit is always the ''primary unit''. These events fire after sightings by the acting unit (unless the player delayed shroud updates). For the first two, the sighted event fires for all sides that can see the unit, other than the unit's own side (even if those sides use neither fog nor shroud). For leveling units, sides that could see the unit before it leveled are excluded. (This is why these events are rare – the leveling unit must have lost a [hides] ability as a result of leveling in order to be seen after, but not before, leveling.) For movement, a sighted event is fired for each side that could see the unit after movement, but not before. In particular, only the starting and ending hexes are considered; a unit that moves through seen hexes but ends movement in a fogged hex does not trigger a sighted event for itself. In all cases where the acting unit is sighted, a (single) ''secondary unit'' is chosen from the sighting team. This choice should be considered arbitrary, but units within their sight range of the acting unit are chosen in preference to units further away.

Sighted events are not triggered by a ''hides'' ability becoming inactive, unless it becomes inactive due to that unit's movement or to that unit ambushing another. (To detect a ''nightstalk'' ability becoming inactive due to time of day, use a ''new_turn'' event. Custom ''hides'' abilities might need similar handling.)

Sighted events have some special caveats for WML authors. First and foremost, {{tag|DirectActionsWML|allow_undo}} should generally be avoided in sighted events. It can be used if current unit positions have no bearing on the event, but otherwise it could cause a replay to go out of sync if a player delays shroud updates and undoes a move. This should not be an onerous restriction, though, as clearing fog will block the ability to undo, regardless of what happens within an event. Secondly, it is currently possible for WML to kill a unit involved in a sighted event before that event fires. If that happens, filters on the killed unit will not match anything and the event may seem to have not fired.

===== enter_hex =====

Triggers for each hex entered during movement, with $x1,$y1 identifying the hex entered and $x2,$y2 identifying the previous hex (just exited). If this event is handled without using {{tag|DirectActionsWML|allow_undo}}, then movement is interrupted, stopping the unit where it is.

'''Note:''' This event behaves a bit unusually if the hex is occupied (and the moving unit is simply passing through). When this happens, $x1,$y1 is still the hex where the event was triggered, but the moving unit (stored in $unit) will be located somewhere earlier in the route (the most recent unoccupied hex). That is, $x1,$y1 will not equal $unit.x,$unit.y (a condition that can be used to detect when the entered hex is occupied). The moving unit will have already spent its movement points to enter the event's hex even though it is has not actually moved from the most recent unoccupied hex.

===== exit_hex =====

Triggers for each hex exited during movement, with $x1,$y1 identifying the hex exited and $x2,$y2 identifying the next hex (to be entered). If this event is handled without using {{tag|DirectActionsWML|allow_undo}}, then movement is interrupted, stopping the unit where it is.

'''Note:''' This event behaves a bit unusually if the hex is occupied (and the moving unit is simply passing through). When this happens, $x1,$y1 is still the hex where the event was triggered, but the moving unit (stored in $unit) will be located somewhere earlier in the route (the most recent unoccupied hex). That is, $x1,$y1 will not equal $unit.x,$unit.y (a condition that can be used to detect when the exited hex is occupied). The moving unit will have already spent its movement points to enter the event's hex even though it is has not actually moved from the most recent unoccupied hex.

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

===== petrified =====
Triggers when the primary unit is hit by an attack with the 'petrifies' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'petrifies' ability).

===== last breath =====

Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered. Use this instead of name=die when you want the primary unit to make a final [message].

===== die =====

Triggers when the primary unit is killed by the secondary unit. ''Note: The primary unit is not removed from the game until the end of this event. The primary unit can still be manipulated, will block other units from taking its hex, and will still be found by standard unit filters (except [have_unit]). To prevent this behavior, you can use [kill] to remove the unit immediately. However, this will stop any (still unfired) other events that also match the unit from firing afterwards, so use with caution.'' If you want to the primary unit to make a final [message], use name=last_breath, see above.

===== capture =====

Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture. This event will be fired before the moveto event. Villages becoming neutral (via [capture_village]) do not fire capture events. The variable $owner_side contains the previous owner side of the village. 0 means neutral.

===== recruit =====

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

===== prerecruit =====

Triggers when the primary unit is recruited (by the secondary unit) but before it is displayed.

===== recall =====

Triggers after the primary unit is recalled (by the secondary unit).

===== prerecall =====

Triggers when the primary unit is recalled (by the secondary unit) but before it is displayed.

===== advance =====

Triggers just before the primary unit is going to advance to another unit, or advance by AMLA. (This is after the player selects which advancement, if there is a choice). If this event removes the unit, changes the unit's type, or reduces the unit's experience below what it needs to advance, then the advancement is aborted. This also applies to advancement by AMLA.

===== pre advance =====

{{DevFeature1.13|0}} Triggers before the unit advancement dialog is shown. If this event removes the unit or reduces the unit's experience below what it needs to advance, then the advancement is aborted.

===== post advance =====

Triggers just after the primary unit has advanced to another unit, or advance by AMLA.

===== select =====

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

===== menu item ''X'' =====

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

==== Custom events ====

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

Example:
#The following is the definition of a custom event "unit recruited"
[event]
name=unit_recruited
first_time_only=no
[message]
speaker=unit
message=_ "Reporting for duty!"
[/message]
[/event]

#This is a standard recruit event that triggers whenever a unit is recruited by side 1
[event]
name=recruit
first_time_only=no
[filter]
[/filter]
[filter_second]
side=1
[/filter_second]

#And now a fire_event tag is used to trigger the previously defined event
[fire_event]
name=unit_recruited
[/fire_event]

#As a result, every time side 1 recruits a unit, this unit says "Reporting for duty!"
[/event]

=== Optional Keys and Tags ===

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

==== first_time_only ====
: Whether the event should be removed from the scenario after it is triggered. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; for example:
: ''first_time_only=yes''
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.
: ''first_time_only=no''
:: The event will trigger every time the criteria are met instead of only the first time.

==== id ====
: If an id is specified, then the event will not be added if another event with the same id already exists. An id will also allow the event to be removed, see below. Supplying a non-empty id= is mandatory in case of a [unit_type][event].

==== remove ====
: Whether to remove an event instead of adding a new one. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; if true, then the contents of the event are ignored and the event with the specified id is removed instead. {{DevFeature1.13|0}} May be a comma separated list.

[event]
id=id_of_event_to_remove
remove=yes
[/event]

Note: {{DevFeature1.13|0}} You can now use [[InternalActionsWML#.5Bremove_event.5D|[remove_event]]] instead (the [event] remove= syntax still works). It also accepts a comma separated list.

[remove_event]
id=id_of_event_to_remove
[/remove_event]

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

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

==== [filter_attack] ====
: Can be used to set additional filtering criteria based on the weapon used by the primary unit. This is usable in the events ''attack'', ''attacker hits'', ''attacker misses'', ''defender hits'', ''defender misses'', ''attack end'', ''last breath'', and ''die''. For more information and filter keys, see [[FilterWML#Filtering Weapons|Filtering Weapons]]. The most commonly used keys are the following.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [filter_second_attack] ====
: Like [filter_attack], but for the weapon used by the secondary unit.

==== [filter_condition] ====
: This tag makes sense inside any sort of event - even those that don't have units, or custom events,... The event will only trigger if this condition evaluates to true.
:* [[ConditionalActionsWML#Condition_Tags|Condition Tags]]
: note: This tag is meant to be used when the firing of an event shall be based on variables/conditions which cannot be retrieved from the filtered units.

==== [filter_side] ====
: The current side (usually the side $side_number) must match the passed [[StandardSideFilter]] for the event to fire.
:* SSF tags and keys as arguments as described in [[StandardSideFilter]].
: note: This tag makes most sense in side turn and turn refresh events. However, all wml events have a current side so one could also prevent e.g. a moveto event from firing if you put a [filter_side] tag there and the moving unit's side doesn't match.

==== 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 [[ActionWML|action tags]] within the [event] tag are executed in the order they are written in.

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

More details in [[ActionWML]].

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

=== Nested Events ===

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

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

==== Delayed Variable Substitution ====

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

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

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

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

== Multiplayer safety ==

In multiplayer it is only safe to use WML that might require synchronization with other players because of input or random numbers (like [message] with input or options or [unstore_unit] where a unit might advance) in the following events. This is because in these cases WML needs data from other players to work right and/or do the same thing for all players. This data is only available after a network synchronization.

List of synchronized events:
* moveto
* enter hex
* exit hex
* sighted
* last breath
* menu item X
* die
* capture
* recruit
* prerecruit
* recall
* prerecall
* advance
* pre advance
* post advance
* attack
* attack end
* attacker hits
* attacker misses
* defender hits
* defender misses
* start
* prestart (prestart are synced but [message][option] & [unstore_unit] advancement choices will do a random decision because UI things don't work during prestart events.)
* new turn
* side turn
* turn X
* side X turn
* side X turn Y
* turn refresh
* side turn end
* side X turn end
* side turn X end
* side X turn Y end
* turn end
* turn X end
* {{DevFeature1.13|0}} enemies defeated
* {{DevFeature1.13|0}} time over
The following are not synced:
* select
* preload
* victory
* defeat
* ai turn

If an event is not listed here, ask someone to be sure.

There is also the possibility of events that are normally synchronized when fired by the engine but can be non-synchronized when fired by WML tags from non-synchronized event. So when you are using them you must be extra careful. For example [unstore_unit] may trigger a unit advancement that will fire ''advance'' and ''post advance'' events.

== A Trap for the Unwary ==

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

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

=== Event IDs ===

This problem can be avoided by setting an '''id''' on the event, i.e.:

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

Events with the same ID will only be accepted once by the engine no matter how many times they are included, and will only be saved once to the scenario's savefile. Events with an ID can also be removed by using the '''remove''' key, i.e.:

[event]
id=doubler_event
remove=yes
[/event]

After that WML is encountered (at toplevel or after created from another event), the event with this ID is removed from the scenario wml, thus firing it has no effect. After an event is removed, it can still be re-added later.

== 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 a message showing the turn number 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]

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

[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, the following example is identical to the first two in that it will display a message showing the turn number on which the nested ''moveto'' event happens, despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

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

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

=== Multiple Nested Events ===

Every delayed_variable_substitution=no causes a variable substitution run on the subevent where it occurs at the spawn time of this event and on all following subevents. For any specific event, variable substitution happens at least one time when the event is executed. For each delayed=no key appearing in itself or in an event of an "older" generation, which is not the toplevel event, an additional variable substitution run is made.
[event]# parent
name=turn 2
#delayed_variable_substitution=no # In the parent event, delayed= has no effect.

[event]# child
name=turn 3
delayed_variable_substitution=no # Causes variable substitution in the child, grandchild and great-grandchild event
# at execution time of the parent event = spawn time of the child event.

[event]# grandchild
name=turn 4
delayed_variable_substitution=yes # no variable substitution in the grandchild and great-grandchild event
# at execution time of the child event = spawn time of the grandchild event

[event]# great-grandchild
name=turn 5
{DEBUG_MSG $turn_number}# output: 2 - value from the variable substitution at execution time of the parent event,
# caused by delayed=no in the child event

{DEBUG_MSG $||turn_number}# output: "$turn_number"
# Each variable substitution transforms a "$|" to a "$" (except when no | left).

{DEBUG_MSG $|turn_number}# output: 5 - from the variable substitution at execution time
# of the great-grandchild event
[/event]
[/event]
[/event]
[/event]

== See Also ==

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

[[Category: WML Reference]]

FAQ

2015-06-22T22:04:16Z

Anonymissimus: /* What are the system requirements? */

{{FAQ/Translations}}
== General ==

===What is Battle for Wesnoth?===
Battle for Wesnoth is a turn-based tactical strategy game with a high fantasy theme, featuring both single-player, and online/hotseat multiplayer combat.

===What license is the game distributed under?===
The project is distributed under the [http://www.fsf.org/copyleft/gpl.html GPL]. All contributors retain copyright on the portions of the project that they contribute. For more information, see [[Wesnoth:Copyrights]].

===How to get informed about new releases?===
Check the front page of the website.

===A new version is out, but where is the download for [Windows, Mac OS X, etc.]?===
The packages provided, other than the source code tarball, are '''not''' part of the official project. The BfW team only releases the game's source code. Binary executables or applications are always contributed by community volunteers. If not for these volunteers, there would never be any downloads for us to enjoy. The volunteers compile the game and upload it on their own time, and sometimes they cannot do this in a timely fashion (or at all, at times). Although there are usual packagers designated for each operating system, there are times when other members of the community are asked to step in and contribute when the usual people cannot.

Every time a new version is released, the usual volunteers are notified by the project leaders. '''Please refrain from making forum posts asking where your download is''' because it doesn't help anything - the packagers already know, and they will get to it as soon as they can. In the past, the Windows and Mac communities have come together to produce home-grown unofficial builds for the community to use, and the renewed interest in community and learning how to compile is generally a good thing.

===Why doesn't Wesnoth have my favorite feature?===
Because we are building this game for ourselves, to suit our own preferences. We're not building the game for you, in large part because this is our hobby, not our job; whether you like it or not is immaterial to us.
You may wonder, then, what the point is of soliciting ideas, as we do on the forum. We, the developers, have certainly come up with many good ideas on our own, but our players often do as well, and generally ones we don't think of ourselves. If a player comes up with an idea we like, we might implement it. Not because they asked for it, but because of its own merits as an addition to our game.

The beautiful thing about the license our game is distributed under, as compared to closed-source, commercial games, is that if you want that feature badly enough, you can take the code and art of our game and modify it yourself; you are free to re-use any work in Wesnoth, as long as you follow the rules of the [http://www.fsf.org/copyleft/gpl.html GPL]. From this, you can build a game exactly the way that you like. Just don't expect us to build that game for you. Building this game is our hobby, not our profession, and you did not pay us to make it; rather, we are the ones who have paid for it, in time and labor.

===Do you want help making this game? How can I help?===
Yes, we want your help. Whether you're a programmer, artist, musician, writer, translator, level designer, playtester, or just have some great suggestions, you're welcome to contribute. How? You can:
* join the [http://www.wesnoth.org/wiki/Project project]
* share your opinions at the [http://www.wesnoth.org/forum/ Forum]
* talk with us on [[Support#IRC|IRC]]
* [[ReportingBugs|report]] bugs you find with Wesnoth and its mainline content
* update the wiki
* play against other players via the [[GettingStarted#Multiplayer|Multiplayer]] menu
* vote for Wesnoth at your favorite gaming web site
* spread the word!

=== What are the system requirements? ===
'''outdated!'''
We are not completely certain, but an x86 running at 400 MHz with 128 MB RAM should be adequate for versions 1.0.2 and below. For versions 1.1 and up we recommend a computer with at least 1 GHz and 512 MB RAM if you run KDE or Gnome as Windowmanager (The game itself needs about 100 MB RAM). Slower machines will have trouble scrolling large maps or processing AI turns with many units. See the [http://www.wesnoth.org/forum/viewtopic.php?t=7384 forum thread] about minimum and recommended system requirements.

=== I'm bored; how do I speed the game up? ===

There are several preferences you can change to shorten the time that the AI takes to make its moves. "Accelerated Speed" will make units move and fight faster. "Skip AI Moves" will not show the AI's units moving from hex to hex. Finally, you can turn off all combat animations via the "Show Combat" option on the Advanced tab.

=== My computer is too slow; how do I speed the game up? ===

First, turn off the music and sound effects. Turning off the color cursors will make your cursor respond faster. If scrolling the map is slow, run the game in "Full Screen" mode, not in a window. Turn off combat, map, and standing unit animations via the "Show Combat", "Animate Map" and "Unit Standing Animations" options on the Advanced tab in the game Preferences. You can try turning off halos and combat results, but this might make gameplay more difficult.
For some tips on tweaking the startup, see [[CustomizingStartup]].

== Gameplay and Controls ==

=== How do I learn to play? ===

If you just want to jump right in, start the game and play the tutorial. If you like reading documentation, see [[WesnothManual]]. At any time while playing, you can select help from the menu button (or hit F1). The online help is quite extensive and provides information on terrains, weapons, traits, abilities, units and a good overview of how to play.

=== My unit leveled up but didn't improve. What happened? ===

This is called "After Maximum Level Advancement" or AMLA for short. While most level 0, 1, and 2 units can advance, some cannot. However, some level 3 units can advance to level 4, or even 5. You can see whether a unit can advance further by right clicking and selecting "description."

After a unit reaches the highest level it can get, every time it reaches a new experience threshold (which increases with each advancement) it gains 3 hitpoints and is restored to a state of full health. This is a minor bonus so that experience gained by maxed out units is not altogether wasted. It is generally better to give experience to lower level units, rather than continue to advance units that have reached their maximum level.

=== I tried to trap an enemy with several weak units, but it still escaped. What happened? ===

Most units exert a zone of control (or ZoC). If an enemy moves into one of the six adjacent hexes, the zone of control will prevent it from moving any farther. However some weak units are level 0, meaning they are so weak that they do not have a ZoC. You can still surround an enemy unit entirely with level 0 units to keep it from escaping, but if there is any gap in your ranks, it could escape.

Also, some units have the "skirmish" ability, which allows them to ignore ZoCs.

=== How can I see where an enemy unit can move next turn? ===

During your turn you can click on an enemy unit. Wesnoth will highlight all the hexes the unit can move to in the next turn. This is useful when trying to arrange your units to block an enemy's movement.

=== There's too much luck in this game! ===

Sooner or later, you will become frustrated when your archmage with four 70% attacks misses all four times. This does not mean that the AI is cheating or the random number generator is futzed. It means you are noticing random negative events more than positive ones. During the development of the game, many mathematicians have done sophisticated statistical analysis of the combat system. Likewise, programmers have examined the random number generator. No flaws have been found, so streaks of "bad" and "good" luck should just be accepted as part of having randomness in Wesnoth. A more detailed rational and discussion of the role that randomness plays in Wesnoth can be found [http://www.wesnoth.org/forum/viewtopic.php?f=6&t=21317&start=0&st=0&sk=t&sd=a here].

Since Wesnoth is GPLed, it is possible that a new development team will someday "fork" the source and produce a version more like Heroes of Might & Magic, with less or no randomness. Until then, don't charge with your horsemen against troll rocklobbers at night...

=== The (random unit) is overpowered/underpowered! ===

The development team has spent years tweaking the units in the game. Each unit has had its gold cost, attack types, combat damage, defensive values, resistances, upgrade paths, and other stats carefully scrutinized and loudly discussed in the forum. However, the game code and the units were being modified right up until the 1.0 release, so some unbalanced units may have slipped through.

If you have evidence to back up your claim, search the forum for past discussions about this unit, and then try posting.

=== The (random scenario) is too hard/easy! ===

See above answer about random units.

=== What do the different difficulty levels do? ===

That depends on the scenario. Usually, the opponent will get more money and be able to recruit higher-level units at higher difficulty levels, and you will have fewer turns available.

== Maps, Scenarios and Campaigns ==

=== How do I beat scenario _______ ? ===

If you are stuck on a scenario in a campaign, you'll probably find a walkthrough at [[MainlineCampaigns]]. Or check out the "Strategies and Tips" forum at http://www.wesnoth.org/forum/viewforum.php?f=3

=== How do I download user campaigns? ===
Choose "Campaigns" in the main Wesnoth menu. Then scroll down to the bottom and choose "Get More Campaigns..." or since 1.1.5 there is a "Get add-ons" button in the main menu. This connects you to the campaign server. In the campaign server you can view a list of all available campaigns and download them, as well as posting or deleting your own campaigns.

If you are behind a firewall you may not be able to connect to the campaign server. In this case try to download the campaign directly from the campaign server at http://addons.wesnoth.org/. If you know how to change your firewall settings, then you should open port 15003 (version 1.1.1 and up) or port 15002 (versions 1.1.0 and lower). For added security, you can restrict traffic over those ports to the campaign server's IP address (currently 88.191.12.200).

=== Are there any tools to help me create maps and scenarios? ===
Yes, the game includes a built-in map editor, that you can use to build the terrain maps for your scenarios.

Unfortunately, there's no simple solution for creating the rest of what constitutes a complete scenario or campaign, which is the [[ReferenceWML|WML]] code. There have been some abandoned attempts at creating complete scenario editors such as [[CampGen]], but they are no longer maintained, nor do they work with the latest stable versions of the game.

You should take a look at the [[Create]] section for information and guides that can help you build your own scenario or campaign. Taking a look at how existing content works is also a good idea.

=== What are the .cfg files and how can I edit them? ===

The .cfg files are plain text files, saved with the file extension ".cfg". You can create and edit them using normal text editors; just save the files in correct format.

Please note that some Windows programs like to add a ".txt" extension, so the file is instead of "my_scenario.cfg" saved as "my_scenario.cfg.txt". And then the Windows Explorer will hide the ".txt" extension by default, so you may not notice it.

'''Notepad''': After you create a document, click "File", "Save as..." and select "Save as type: All files". To open the document, click "File", "Open..." and select "Files of type: All files (*.*)". If you open someone else's document, and the end-of-line symbols are displayed as small rectangles, you have to use another editor.

'''WordPad''': After you create a document, click "File", "Save as..." and select "Save as type: Text Document". After the document is saved, close WordPad and remove the ".txt" extension from file. To open the document, click "File", "Open..." and select "Files of type: All documents (*.*)".

Starting with the 1.9.x branch, there is a new IDE for helping User Made Content Authors to easily develop Wesnoth Add-ons. The website and details can be found at: http://eclipse.wesnoth.org

=== I already created an add-on and published it on the server. How can I get translations for the campaign? ===
Just have a look at [[WesCamp]]. This project is the easiest way to get translations for your campaign. All the info you need you can find at [[WesCamp]].

===How do I place an object or unit on my map with the map editor?===
You can't. You need to make a scenario file. There are more details on the [[BuildingMaps|maps]] page.

== Multiplayer ==

===How do I connect to a multiplayer server, when I sit behind a restrictive firewall?===

You have to open outgoing TCP port 15000 - 14997 (depending on the version you use) to play multiplayer games over the internet on the official servers.

===How to find players for multiplayer game?===
Hang around for a while on multiplayer servers and you might find someone to play with. If you observe other people playing you will get informed when someone joins the servers. Maybe you find someone willing to play in the [[Support#IRC|IRC]] channel dedicated to Wesnoth, #wesnoth at irc.freenode.net.

===How to save and load a multiplayer game===

Save the game. Give it a good name, so that you can find it among the other saved games.

Create new game. (Give it a name like "private game for X and Y", so that other players will not try joining it, and you do not have to explain or kick them.) The first item in the map/scenario list is "Saved games", select this. Choose the saved game. Wait for the other player(s) to connect. Start the game.

===How can I make my computer into a dedicated Wesnoth server?===

To setup a dedicated Wesnoth server, you have to compile the game with the "--enable-server" flag, and after you install, simply run wesnothd from the console. This will start the server, listening on TCP port 15000. To compile the server only you can use the flags "--disable-game --enable-server". If you aren't using a linux or mac operating system, there are a few ways you can compile on Windows... [[CompilingWesnoth/CrossCompiling|here is one way]].

'''Note:''' Packages for Wesnoth 1.4 and later include wesnothd by default since it's required by the "Host a network game" option from the Multiplayer menu, which is the preferred option for temporarily hosting a server instance to play in a LAN or privately through the Internet.

===Which versions of Wesnoth can play together?===

You only need to make sure you are using the same minor version number (6 in "1.6.x", 8 in "1.8.x" and so on) corresponding to stable branch releases. If you are using a development release (odd minor version numbers), you must be using exactly the same version number as other clients, to avoid out-of-sync (OOS) issues in multiplayer.

If you are using user-made eras or MP scenarios, all players should make sure they are using the same, latest version of the add-on.

== Translations ==

===Where can I find more information about translating Wesnoth?===
See [[WesnothTranslations]] for a list of currently maintained projects, and methods for contacting their maintainers and volunteering for help, and instructions for starting your own translation if it isn't included in the game already. [http://gettext.wesnoth.org] shows the current progress translations for different game development and stable branches, mainline campaigns and user-made add-ons.

== Other Questions You Have ==

The best way to get answers to less-frequently asked questions is by visiting the official [http://forums.wesnoth.org Battle for Wesnoth forums]. There are plenty of people willing to help. Make sure you read ALL of the forum sticky notes and announcements before posting!

[[Category:Troubleshooting and Bugs]]

FAQ

2015-06-22T21:53:45Z

Anonymissimus: /* What are the system requirements? */

{{FAQ/Translations}}
== General ==

===What is Battle for Wesnoth?===
Battle for Wesnoth is a turn-based tactical strategy game with a high fantasy theme, featuring both single-player, and online/hotseat multiplayer combat.

===What license is the game distributed under?===
The project is distributed under the [http://www.fsf.org/copyleft/gpl.html GPL]. All contributors retain copyright on the portions of the project that they contribute. For more information, see [[Wesnoth:Copyrights]].

===How to get informed about new releases?===
Check the front page of the website.

===A new version is out, but where is the download for [Windows, Mac OS X, etc.]?===
The packages provided, other than the source code tarball, are '''not''' part of the official project. The BfW team only releases the game's source code. Binary executables or applications are always contributed by community volunteers. If not for these volunteers, there would never be any downloads for us to enjoy. The volunteers compile the game and upload it on their own time, and sometimes they cannot do this in a timely fashion (or at all, at times). Although there are usual packagers designated for each operating system, there are times when other members of the community are asked to step in and contribute when the usual people cannot.

Every time a new version is released, the usual volunteers are notified by the project leaders. '''Please refrain from making forum posts asking where your download is''' because it doesn't help anything - the packagers already know, and they will get to it as soon as they can. In the past, the Windows and Mac communities have come together to produce home-grown unofficial builds for the community to use, and the renewed interest in community and learning how to compile is generally a good thing.

===Why doesn't Wesnoth have my favorite feature?===
Because we are building this game for ourselves, to suit our own preferences. We're not building the game for you, in large part because this is our hobby, not our job; whether you like it or not is immaterial to us.
You may wonder, then, what the point is of soliciting ideas, as we do on the forum. We, the developers, have certainly come up with many good ideas on our own, but our players often do as well, and generally ones we don't think of ourselves. If a player comes up with an idea we like, we might implement it. Not because they asked for it, but because of its own merits as an addition to our game.

The beautiful thing about the license our game is distributed under, as compared to closed-source, commercial games, is that if you want that feature badly enough, you can take the code and art of our game and modify it yourself; you are free to re-use any work in Wesnoth, as long as you follow the rules of the [http://www.fsf.org/copyleft/gpl.html GPL]. From this, you can build a game exactly the way that you like. Just don't expect us to build that game for you. Building this game is our hobby, not our profession, and you did not pay us to make it; rather, we are the ones who have paid for it, in time and labor.

===Do you want help making this game? How can I help?===
Yes, we want your help. Whether you're a programmer, artist, musician, writer, translator, level designer, playtester, or just have some great suggestions, you're welcome to contribute. How? You can:
* join the [http://www.wesnoth.org/wiki/Project project]
* share your opinions at the [http://www.wesnoth.org/forum/ Forum]
* talk with us on [[Support#IRC|IRC]]
* [[ReportingBugs|report]] bugs you find with Wesnoth and its mainline content
* update the wiki
* play against other players via the [[GettingStarted#Multiplayer|Multiplayer]] menu
* vote for Wesnoth at your favorite gaming web site
* spread the word!

=== What are the system requirements? ===
'''outdated!'''
We are not completely certain, but an x86 running at 400 MHz with 128 MB RAM should be adequate for versions 1.0.2 and below. For versions 1.1 and up we recommend a computer with at least 1 GHz and 512 MB RAM if you run KDE or Gnome as Windowmanager (The game itself needs about 100 MB RAM). Slower machines will have trouble scrolling large maps or processing AI turns with many units. See the [http://www.wesnoth.org/forum/viewtopic.php?t=7384 forum thread] about minimum and recommended system requirements.

'''update'''
I happened to set up a 1GHz 512MB RAM machine with win xp and a GeForce2 MX/MX 400 with corresponding drivers. This is hardware from about 2000. Scrolling the map is jumpy, but not much, and multiplayer in wesnoth 1.12.3+dev, Isar's Cross, runs fine otherwise. Of course, make sure you reserve as much resources for wesnoth as possible, deactivate animated map and standing animations, and don't have too many AI units on the map. I've played wesnoth on a weaker machine too and would call the above a recommended minimum for enjoyable play. Alternatively, use a lightweight Linux distro. Singleplayer performance seems, for some reason, a good deal better than multiplayer, especially scrolling the map. When in multiplayer lobby, don't filter for games, it's a total CPU eater. -anonymissimus, June 2015

=== I'm bored; how do I speed the game up? ===

There are several preferences you can change to shorten the time that the AI takes to make its moves. "Accelerated Speed" will make units move and fight faster. "Skip AI Moves" will not show the AI's units moving from hex to hex. Finally, you can turn off all combat animations via the "Show Combat" option on the Advanced tab.

=== My computer is too slow; how do I speed the game up? ===

First, turn off the music and sound effects. Turning off the color cursors will make your cursor respond faster. If scrolling the map is slow, run the game in "Full Screen" mode, not in a window. Turn off combat, map, and standing unit animations via the "Show Combat", "Animate Map" and "Unit Standing Animations" options on the Advanced tab in the game Preferences. You can try turning off halos and combat results, but this might make gameplay more difficult.
For some tips on tweaking the startup, see [[CustomizingStartup]].

== Gameplay and Controls ==

=== How do I learn to play? ===

If you just want to jump right in, start the game and play the tutorial. If you like reading documentation, see [[WesnothManual]]. At any time while playing, you can select help from the menu button (or hit F1). The online help is quite extensive and provides information on terrains, weapons, traits, abilities, units and a good overview of how to play.

=== My unit leveled up but didn't improve. What happened? ===

This is called "After Maximum Level Advancement" or AMLA for short. While most level 0, 1, and 2 units can advance, some cannot. However, some level 3 units can advance to level 4, or even 5. You can see whether a unit can advance further by right clicking and selecting "description."

After a unit reaches the highest level it can get, every time it reaches a new experience threshold (which increases with each advancement) it gains 3 hitpoints and is restored to a state of full health. This is a minor bonus so that experience gained by maxed out units is not altogether wasted. It is generally better to give experience to lower level units, rather than continue to advance units that have reached their maximum level.

=== I tried to trap an enemy with several weak units, but it still escaped. What happened? ===

Most units exert a zone of control (or ZoC). If an enemy moves into one of the six adjacent hexes, the zone of control will prevent it from moving any farther. However some weak units are level 0, meaning they are so weak that they do not have a ZoC. You can still surround an enemy unit entirely with level 0 units to keep it from escaping, but if there is any gap in your ranks, it could escape.

Also, some units have the "skirmish" ability, which allows them to ignore ZoCs.

=== How can I see where an enemy unit can move next turn? ===

During your turn you can click on an enemy unit. Wesnoth will highlight all the hexes the unit can move to in the next turn. This is useful when trying to arrange your units to block an enemy's movement.

=== There's too much luck in this game! ===

Sooner or later, you will become frustrated when your archmage with four 70% attacks misses all four times. This does not mean that the AI is cheating or the random number generator is futzed. It means you are noticing random negative events more than positive ones. During the development of the game, many mathematicians have done sophisticated statistical analysis of the combat system. Likewise, programmers have examined the random number generator. No flaws have been found, so streaks of "bad" and "good" luck should just be accepted as part of having randomness in Wesnoth. A more detailed rational and discussion of the role that randomness plays in Wesnoth can be found [http://www.wesnoth.org/forum/viewtopic.php?f=6&t=21317&start=0&st=0&sk=t&sd=a here].

Since Wesnoth is GPLed, it is possible that a new development team will someday "fork" the source and produce a version more like Heroes of Might & Magic, with less or no randomness. Until then, don't charge with your horsemen against troll rocklobbers at night...

=== The (random unit) is overpowered/underpowered! ===

The development team has spent years tweaking the units in the game. Each unit has had its gold cost, attack types, combat damage, defensive values, resistances, upgrade paths, and other stats carefully scrutinized and loudly discussed in the forum. However, the game code and the units were being modified right up until the 1.0 release, so some unbalanced units may have slipped through.

If you have evidence to back up your claim, search the forum for past discussions about this unit, and then try posting.

=== The (random scenario) is too hard/easy! ===

See above answer about random units.

=== What do the different difficulty levels do? ===

That depends on the scenario. Usually, the opponent will get more money and be able to recruit higher-level units at higher difficulty levels, and you will have fewer turns available.

== Maps, Scenarios and Campaigns ==

=== How do I beat scenario _______ ? ===

If you are stuck on a scenario in a campaign, you'll probably find a walkthrough at [[MainlineCampaigns]]. Or check out the "Strategies and Tips" forum at http://www.wesnoth.org/forum/viewforum.php?f=3

=== How do I download user campaigns? ===
Choose "Campaigns" in the main Wesnoth menu. Then scroll down to the bottom and choose "Get More Campaigns..." or since 1.1.5 there is a "Get add-ons" button in the main menu. This connects you to the campaign server. In the campaign server you can view a list of all available campaigns and download them, as well as posting or deleting your own campaigns.

If you are behind a firewall you may not be able to connect to the campaign server. In this case try to download the campaign directly from the campaign server at http://addons.wesnoth.org/. If you know how to change your firewall settings, then you should open port 15003 (version 1.1.1 and up) or port 15002 (versions 1.1.0 and lower). For added security, you can restrict traffic over those ports to the campaign server's IP address (currently 88.191.12.200).

=== Are there any tools to help me create maps and scenarios? ===
Yes, the game includes a built-in map editor, that you can use to build the terrain maps for your scenarios.

Unfortunately, there's no simple solution for creating the rest of what constitutes a complete scenario or campaign, which is the [[ReferenceWML|WML]] code. There have been some abandoned attempts at creating complete scenario editors such as [[CampGen]], but they are no longer maintained, nor do they work with the latest stable versions of the game.

You should take a look at the [[Create]] section for information and guides that can help you build your own scenario or campaign. Taking a look at how existing content works is also a good idea.

=== What are the .cfg files and how can I edit them? ===

The .cfg files are plain text files, saved with the file extension ".cfg". You can create and edit them using normal text editors; just save the files in correct format.

Please note that some Windows programs like to add a ".txt" extension, so the file is instead of "my_scenario.cfg" saved as "my_scenario.cfg.txt". And then the Windows Explorer will hide the ".txt" extension by default, so you may not notice it.

'''Notepad''': After you create a document, click "File", "Save as..." and select "Save as type: All files". To open the document, click "File", "Open..." and select "Files of type: All files (*.*)". If you open someone else's document, and the end-of-line symbols are displayed as small rectangles, you have to use another editor.

'''WordPad''': After you create a document, click "File", "Save as..." and select "Save as type: Text Document". After the document is saved, close WordPad and remove the ".txt" extension from file. To open the document, click "File", "Open..." and select "Files of type: All documents (*.*)".

Starting with the 1.9.x branch, there is a new IDE for helping User Made Content Authors to easily develop Wesnoth Add-ons. The website and details can be found at: http://eclipse.wesnoth.org

=== I already created an add-on and published it on the server. How can I get translations for the campaign? ===
Just have a look at [[WesCamp]]. This project is the easiest way to get translations for your campaign. All the info you need you can find at [[WesCamp]].

===How do I place an object or unit on my map with the map editor?===
You can't. You need to make a scenario file. There are more details on the [[BuildingMaps|maps]] page.

== Multiplayer ==

===How do I connect to a multiplayer server, when I sit behind a restrictive firewall?===

You have to open outgoing TCP port 15000 - 14997 (depending on the version you use) to play multiplayer games over the internet on the official servers.

===How to find players for multiplayer game?===
Hang around for a while on multiplayer servers and you might find someone to play with. If you observe other people playing you will get informed when someone joins the servers. Maybe you find someone willing to play in the [[Support#IRC|IRC]] channel dedicated to Wesnoth, #wesnoth at irc.freenode.net.

===How to save and load a multiplayer game===

Save the game. Give it a good name, so that you can find it among the other saved games.

Create new game. (Give it a name like "private game for X and Y", so that other players will not try joining it, and you do not have to explain or kick them.) The first item in the map/scenario list is "Saved games", select this. Choose the saved game. Wait for the other player(s) to connect. Start the game.

===How can I make my computer into a dedicated Wesnoth server?===

To setup a dedicated Wesnoth server, you have to compile the game with the "--enable-server" flag, and after you install, simply run wesnothd from the console. This will start the server, listening on TCP port 15000. To compile the server only you can use the flags "--disable-game --enable-server". If you aren't using a linux or mac operating system, there are a few ways you can compile on Windows... [[CompilingWesnoth/CrossCompiling|here is one way]].

'''Note:''' Packages for Wesnoth 1.4 and later include wesnothd by default since it's required by the "Host a network game" option from the Multiplayer menu, which is the preferred option for temporarily hosting a server instance to play in a LAN or privately through the Internet.

===Which versions of Wesnoth can play together?===

You only need to make sure you are using the same minor version number (6 in "1.6.x", 8 in "1.8.x" and so on) corresponding to stable branch releases. If you are using a development release (odd minor version numbers), you must be using exactly the same version number as other clients, to avoid out-of-sync (OOS) issues in multiplayer.

If you are using user-made eras or MP scenarios, all players should make sure they are using the same, latest version of the add-on.

== Translations ==

===Where can I find more information about translating Wesnoth?===
See [[WesnothTranslations]] for a list of currently maintained projects, and methods for contacting their maintainers and volunteering for help, and instructions for starting your own translation if it isn't included in the game already. [http://gettext.wesnoth.org] shows the current progress translations for different game development and stable branches, mainline campaigns and user-made add-ons.

== Other Questions You Have ==

The best way to get answers to less-frequently asked questions is by visiting the official [http://forums.wesnoth.org Battle for Wesnoth forums]. There are plenty of people willing to help. Make sure you read ALL of the forum sticky notes and announcements before posting!

[[Category:Troubleshooting and Bugs]]

FAQ

2015-06-22T17:12:01Z

Anonymissimus: /* What are the system requirements? */

{{FAQ/Translations}}
== General ==

===What is Battle for Wesnoth?===
Battle for Wesnoth is a turn-based tactical strategy game with a high fantasy theme, featuring both single-player, and online/hotseat multiplayer combat.

===What license is the game distributed under?===
The project is distributed under the [http://www.fsf.org/copyleft/gpl.html GPL]. All contributors retain copyright on the portions of the project that they contribute. For more information, see [[Wesnoth:Copyrights]].

===How to get informed about new releases?===
Check the front page of the website.

===A new version is out, but where is the download for [Windows, Mac OS X, etc.]?===
The packages provided, other than the source code tarball, are '''not''' part of the official project. The BfW team only releases the game's source code. Binary executables or applications are always contributed by community volunteers. If not for these volunteers, there would never be any downloads for us to enjoy. The volunteers compile the game and upload it on their own time, and sometimes they cannot do this in a timely fashion (or at all, at times). Although there are usual packagers designated for each operating system, there are times when other members of the community are asked to step in and contribute when the usual people cannot.

Every time a new version is released, the usual volunteers are notified by the project leaders. '''Please refrain from making forum posts asking where your download is''' because it doesn't help anything - the packagers already know, and they will get to it as soon as they can. In the past, the Windows and Mac communities have come together to produce home-grown unofficial builds for the community to use, and the renewed interest in community and learning how to compile is generally a good thing.

===Why doesn't Wesnoth have my favorite feature?===
Because we are building this game for ourselves, to suit our own preferences. We're not building the game for you, in large part because this is our hobby, not our job; whether you like it or not is immaterial to us.
You may wonder, then, what the point is of soliciting ideas, as we do on the forum. We, the developers, have certainly come up with many good ideas on our own, but our players often do as well, and generally ones we don't think of ourselves. If a player comes up with an idea we like, we might implement it. Not because they asked for it, but because of its own merits as an addition to our game.

The beautiful thing about the license our game is distributed under, as compared to closed-source, commercial games, is that if you want that feature badly enough, you can take the code and art of our game and modify it yourself; you are free to re-use any work in Wesnoth, as long as you follow the rules of the [http://www.fsf.org/copyleft/gpl.html GPL]. From this, you can build a game exactly the way that you like. Just don't expect us to build that game for you. Building this game is our hobby, not our profession, and you did not pay us to make it; rather, we are the ones who have paid for it, in time and labor.

===Do you want help making this game? How can I help?===
Yes, we want your help. Whether you're a programmer, artist, musician, writer, translator, level designer, playtester, or just have some great suggestions, you're welcome to contribute. How? You can:
* join the [http://www.wesnoth.org/wiki/Project project]
* share your opinions at the [http://www.wesnoth.org/forum/ Forum]
* talk with us on [[Support#IRC|IRC]]
* [[ReportingBugs|report]] bugs you find with Wesnoth and its mainline content
* update the wiki
* play against other players via the [[GettingStarted#Multiplayer|Multiplayer]] menu
* vote for Wesnoth at your favorite gaming web site
* spread the word!

=== What are the system requirements? ===
'''outdated!'''
We are not completely certain, but an x86 running at 400 MHz with 128 MB RAM should be adequate for versions 1.0.2 and below. For versions 1.1 and up we recommend a computer with at least 1 GHz and 512 MB RAM if you run KDE or Gnome as Windowmanager (The game itself needs about 100 MB RAM). Slower machines will have trouble scrolling large maps or processing AI turns with many units. See the [http://www.wesnoth.org/forum/viewtopic.php?t=7384 forum thread] about minimum and recommended system requirements.

'''update'''
I happened to set up a 1GHz 512MB RAM machine with win xp and a GeForce2 MX/MX 400 with corresponding drivers. This is hardware from about 2000. Scrolling the map is jumpy, but not much, and multiplayer in wesnoth 1.12.3+dev, Isar's Cross, runs fine otherwise. Of course, make sure you reserve as much resources for wesnoth as possible, deactivate animated map and standing animations, and don't have too many AI units on the map. I've played wesnoth on a weaker machine too and would call the above a recommended minimum for enjoyable play. Alternatively, use a lightweight Linux distro. -anonymissimus, June 2015

=== I'm bored; how do I speed the game up? ===

There are several preferences you can change to shorten the time that the AI takes to make its moves. "Accelerated Speed" will make units move and fight faster. "Skip AI Moves" will not show the AI's units moving from hex to hex. Finally, you can turn off all combat animations via the "Show Combat" option on the Advanced tab.

=== My computer is too slow; how do I speed the game up? ===

First, turn off the music and sound effects. Turning off the color cursors will make your cursor respond faster. If scrolling the map is slow, run the game in "Full Screen" mode, not in a window. Turn off combat, map, and standing unit animations via the "Show Combat", "Animate Map" and "Unit Standing Animations" options on the Advanced tab in the game Preferences. You can try turning off halos and combat results, but this might make gameplay more difficult.
For some tips on tweaking the startup, see [[CustomizingStartup]].

== Gameplay and Controls ==

=== How do I learn to play? ===

If you just want to jump right in, start the game and play the tutorial. If you like reading documentation, see [[WesnothManual]]. At any time while playing, you can select help from the menu button (or hit F1). The online help is quite extensive and provides information on terrains, weapons, traits, abilities, units and a good overview of how to play.

=== My unit leveled up but didn't improve. What happened? ===

This is called "After Maximum Level Advancement" or AMLA for short. While most level 0, 1, and 2 units can advance, some cannot. However, some level 3 units can advance to level 4, or even 5. You can see whether a unit can advance further by right clicking and selecting "description."

After a unit reaches the highest level it can get, every time it reaches a new experience threshold (which increases with each advancement) it gains 3 hitpoints and is restored to a state of full health. This is a minor bonus so that experience gained by maxed out units is not altogether wasted. It is generally better to give experience to lower level units, rather than continue to advance units that have reached their maximum level.

=== I tried to trap an enemy with several weak units, but it still escaped. What happened? ===

Most units exert a zone of control (or ZoC). If an enemy moves into one of the six adjacent hexes, the zone of control will prevent it from moving any farther. However some weak units are level 0, meaning they are so weak that they do not have a ZoC. You can still surround an enemy unit entirely with level 0 units to keep it from escaping, but if there is any gap in your ranks, it could escape.

Also, some units have the "skirmish" ability, which allows them to ignore ZoCs.

=== How can I see where an enemy unit can move next turn? ===

During your turn you can click on an enemy unit. Wesnoth will highlight all the hexes the unit can move to in the next turn. This is useful when trying to arrange your units to block an enemy's movement.

=== There's too much luck in this game! ===

Sooner or later, you will become frustrated when your archmage with four 70% attacks misses all four times. This does not mean that the AI is cheating or the random number generator is futzed. It means you are noticing random negative events more than positive ones. During the development of the game, many mathematicians have done sophisticated statistical analysis of the combat system. Likewise, programmers have examined the random number generator. No flaws have been found, so streaks of "bad" and "good" luck should just be accepted as part of having randomness in Wesnoth. A more detailed rational and discussion of the role that randomness plays in Wesnoth can be found [http://www.wesnoth.org/forum/viewtopic.php?f=6&t=21317&start=0&st=0&sk=t&sd=a here].

Since Wesnoth is GPLed, it is possible that a new development team will someday "fork" the source and produce a version more like Heroes of Might & Magic, with less or no randomness. Until then, don't charge with your horsemen against troll rocklobbers at night...

=== The (random unit) is overpowered/underpowered! ===

The development team has spent years tweaking the units in the game. Each unit has had its gold cost, attack types, combat damage, defensive values, resistances, upgrade paths, and other stats carefully scrutinized and loudly discussed in the forum. However, the game code and the units were being modified right up until the 1.0 release, so some unbalanced units may have slipped through.

If you have evidence to back up your claim, search the forum for past discussions about this unit, and then try posting.

=== The (random scenario) is too hard/easy! ===

See above answer about random units.

=== What do the different difficulty levels do? ===

That depends on the scenario. Usually, the opponent will get more money and be able to recruit higher-level units at higher difficulty levels, and you will have fewer turns available.

== Maps, Scenarios and Campaigns ==

=== How do I beat scenario _______ ? ===

If you are stuck on a scenario in a campaign, you'll probably find a walkthrough at [[MainlineCampaigns]]. Or check out the "Strategies and Tips" forum at http://www.wesnoth.org/forum/viewforum.php?f=3

=== How do I download user campaigns? ===
Choose "Campaigns" in the main Wesnoth menu. Then scroll down to the bottom and choose "Get More Campaigns..." or since 1.1.5 there is a "Get add-ons" button in the main menu. This connects you to the campaign server. In the campaign server you can view a list of all available campaigns and download them, as well as posting or deleting your own campaigns.

If you are behind a firewall you may not be able to connect to the campaign server. In this case try to download the campaign directly from the campaign server at http://addons.wesnoth.org/. If you know how to change your firewall settings, then you should open port 15003 (version 1.1.1 and up) or port 15002 (versions 1.1.0 and lower). For added security, you can restrict traffic over those ports to the campaign server's IP address (currently 88.191.12.200).

=== Are there any tools to help me create maps and scenarios? ===
Yes, the game includes a built-in map editor, that you can use to build the terrain maps for your scenarios.

Unfortunately, there's no simple solution for creating the rest of what constitutes a complete scenario or campaign, which is the [[ReferenceWML|WML]] code. There have been some abandoned attempts at creating complete scenario editors such as [[CampGen]], but they are no longer maintained, nor do they work with the latest stable versions of the game.

You should take a look at the [[Create]] section for information and guides that can help you build your own scenario or campaign. Taking a look at how existing content works is also a good idea.

=== What are the .cfg files and how can I edit them? ===

The .cfg files are plain text files, saved with the file extension ".cfg". You can create and edit them using normal text editors; just save the files in correct format.

Please note that some Windows programs like to add a ".txt" extension, so the file is instead of "my_scenario.cfg" saved as "my_scenario.cfg.txt". And then the Windows Explorer will hide the ".txt" extension by default, so you may not notice it.

'''Notepad''': After you create a document, click "File", "Save as..." and select "Save as type: All files". To open the document, click "File", "Open..." and select "Files of type: All files (*.*)". If you open someone else's document, and the end-of-line symbols are displayed as small rectangles, you have to use another editor.

'''WordPad''': After you create a document, click "File", "Save as..." and select "Save as type: Text Document". After the document is saved, close WordPad and remove the ".txt" extension from file. To open the document, click "File", "Open..." and select "Files of type: All documents (*.*)".

Starting with the 1.9.x branch, there is a new IDE for helping User Made Content Authors to easily develop Wesnoth Add-ons. The website and details can be found at: http://eclipse.wesnoth.org

=== I already created an add-on and published it on the server. How can I get translations for the campaign? ===
Just have a look at [[WesCamp]]. This project is the easiest way to get translations for your campaign. All the info you need you can find at [[WesCamp]].

===How do I place an object or unit on my map with the map editor?===
You can't. You need to make a scenario file. There are more details on the [[BuildingMaps|maps]] page.

== Multiplayer ==

===How do I connect to a multiplayer server, when I sit behind a restrictive firewall?===

You have to open outgoing TCP port 15000 - 14997 (depending on the version you use) to play multiplayer games over the internet on the official servers.

===How to find players for multiplayer game?===
Hang around for a while on multiplayer servers and you might find someone to play with. If you observe other people playing you will get informed when someone joins the servers. Maybe you find someone willing to play in the [[Support#IRC|IRC]] channel dedicated to Wesnoth, #wesnoth at irc.freenode.net.

===How to save and load a multiplayer game===

Save the game. Give it a good name, so that you can find it among the other saved games.

Create new game. (Give it a name like "private game for X and Y", so that other players will not try joining it, and you do not have to explain or kick them.) The first item in the map/scenario list is "Saved games", select this. Choose the saved game. Wait for the other player(s) to connect. Start the game.

===How can I make my computer into a dedicated Wesnoth server?===

To setup a dedicated Wesnoth server, you have to compile the game with the "--enable-server" flag, and after you install, simply run wesnothd from the console. This will start the server, listening on TCP port 15000. To compile the server only you can use the flags "--disable-game --enable-server". If you aren't using a linux or mac operating system, there are a few ways you can compile on Windows... [[CompilingWesnoth/CrossCompiling|here is one way]].

'''Note:''' Packages for Wesnoth 1.4 and later include wesnothd by default since it's required by the "Host a network game" option from the Multiplayer menu, which is the preferred option for temporarily hosting a server instance to play in a LAN or privately through the Internet.

===Which versions of Wesnoth can play together?===

You only need to make sure you are using the same minor version number (6 in "1.6.x", 8 in "1.8.x" and so on) corresponding to stable branch releases. If you are using a development release (odd minor version numbers), you must be using exactly the same version number as other clients, to avoid out-of-sync (OOS) issues in multiplayer.

If you are using user-made eras or MP scenarios, all players should make sure they are using the same, latest version of the add-on.

== Translations ==

===Where can I find more information about translating Wesnoth?===
See [[WesnothTranslations]] for a list of currently maintained projects, and methods for contacting their maintainers and volunteering for help, and instructions for starting your own translation if it isn't included in the game already. [http://gettext.wesnoth.org] shows the current progress translations for different game development and stable branches, mainline campaigns and user-made add-ons.

== Other Questions You Have ==

The best way to get answers to less-frequently asked questions is by visiting the official [http://forums.wesnoth.org Battle for Wesnoth forums]. There are plenty of people willing to help. Make sure you read ALL of the forum sticky notes and announcements before posting!

[[Category:Troubleshooting and Bugs]]

FAQ

2015-06-22T14:28:09Z

Anonymissimus: /* What are the system requirements? */

{{FAQ/Translations}}
== General ==

===What is Battle for Wesnoth?===
Battle for Wesnoth is a turn-based tactical strategy game with a high fantasy theme, featuring both single-player, and online/hotseat multiplayer combat.

===What license is the game distributed under?===
The project is distributed under the [http://www.fsf.org/copyleft/gpl.html GPL]. All contributors retain copyright on the portions of the project that they contribute. For more information, see [[Wesnoth:Copyrights]].

===How to get informed about new releases?===
Check the front page of the website.

===A new version is out, but where is the download for [Windows, Mac OS X, etc.]?===
The packages provided, other than the source code tarball, are '''not''' part of the official project. The BfW team only releases the game's source code. Binary executables or applications are always contributed by community volunteers. If not for these volunteers, there would never be any downloads for us to enjoy. The volunteers compile the game and upload it on their own time, and sometimes they cannot do this in a timely fashion (or at all, at times). Although there are usual packagers designated for each operating system, there are times when other members of the community are asked to step in and contribute when the usual people cannot.

Every time a new version is released, the usual volunteers are notified by the project leaders. '''Please refrain from making forum posts asking where your download is''' because it doesn't help anything - the packagers already know, and they will get to it as soon as they can. In the past, the Windows and Mac communities have come together to produce home-grown unofficial builds for the community to use, and the renewed interest in community and learning how to compile is generally a good thing.

===Why doesn't Wesnoth have my favorite feature?===
Because we are building this game for ourselves, to suit our own preferences. We're not building the game for you, in large part because this is our hobby, not our job; whether you like it or not is immaterial to us.
You may wonder, then, what the point is of soliciting ideas, as we do on the forum. We, the developers, have certainly come up with many good ideas on our own, but our players often do as well, and generally ones we don't think of ourselves. If a player comes up with an idea we like, we might implement it. Not because they asked for it, but because of its own merits as an addition to our game.

The beautiful thing about the license our game is distributed under, as compared to closed-source, commercial games, is that if you want that feature badly enough, you can take the code and art of our game and modify it yourself; you are free to re-use any work in Wesnoth, as long as you follow the rules of the [http://www.fsf.org/copyleft/gpl.html GPL]. From this, you can build a game exactly the way that you like. Just don't expect us to build that game for you. Building this game is our hobby, not our profession, and you did not pay us to make it; rather, we are the ones who have paid for it, in time and labor.

===Do you want help making this game? How can I help?===
Yes, we want your help. Whether you're a programmer, artist, musician, writer, translator, level designer, playtester, or just have some great suggestions, you're welcome to contribute. How? You can:
* join the [http://www.wesnoth.org/wiki/Project project]
* share your opinions at the [http://www.wesnoth.org/forum/ Forum]
* talk with us on [[Support#IRC|IRC]]
* [[ReportingBugs|report]] bugs you find with Wesnoth and its mainline content
* update the wiki
* play against other players via the [[GettingStarted#Multiplayer|Multiplayer]] menu
* vote for Wesnoth at your favorite gaming web site
* spread the word!

=== What are the system requirements? ===
'''outdated!'''
We are not completely certain, but an x86 running at 400 MHz with 128 MB RAM should be adequate for versions 1.0.2 and below. For versions 1.1 and up we recommend a computer with at least 1 GHz and 512 MB RAM if you run KDE or Gnome as Windowmanager (The game itself needs about 100 MB RAM). Slower machines will have trouble scrolling large maps or processing AI turns with many units. See the [http://www.wesnoth.org/forum/viewtopic.php?t=7384 forum thread] about minimum and recommended system requirements.

'''update'''
I happened to set up a 1GHz 512MB RAM machine with win xp and a GeForce2 MX/MX 400 with corresponding drivers. This is hardware from about 2000. Scrolling the map is jumpy, but multiplayer in wesnoth 1.12.3+dev, Isar's Cross, runs fine otherwise. Of course, make sure you reserve as much resources for wesnoth as possible, deactivate animated map and standing animations, and don't have too many AI units on the map. -anonymissimus, June 2015

=== I'm bored; how do I speed the game up? ===

There are several preferences you can change to shorten the time that the AI takes to make its moves. "Accelerated Speed" will make units move and fight faster. "Skip AI Moves" will not show the AI's units moving from hex to hex. Finally, you can turn off all combat animations via the "Show Combat" option on the Advanced tab.

=== My computer is too slow; how do I speed the game up? ===

First, turn off the music and sound effects. Turning off the color cursors will make your cursor respond faster. If scrolling the map is slow, run the game in "Full Screen" mode, not in a window. Turn off combat, map, and standing unit animations via the "Show Combat", "Animate Map" and "Unit Standing Animations" options on the Advanced tab in the game Preferences. You can try turning off halos and combat results, but this might make gameplay more difficult.
For some tips on tweaking the startup, see [[CustomizingStartup]].

== Gameplay and Controls ==

=== How do I learn to play? ===

If you just want to jump right in, start the game and play the tutorial. If you like reading documentation, see [[WesnothManual]]. At any time while playing, you can select help from the menu button (or hit F1). The online help is quite extensive and provides information on terrains, weapons, traits, abilities, units and a good overview of how to play.

=== My unit leveled up but didn't improve. What happened? ===

This is called "After Maximum Level Advancement" or AMLA for short. While most level 0, 1, and 2 units can advance, some cannot. However, some level 3 units can advance to level 4, or even 5. You can see whether a unit can advance further by right clicking and selecting "description."

After a unit reaches the highest level it can get, every time it reaches a new experience threshold (which increases with each advancement) it gains 3 hitpoints and is restored to a state of full health. This is a minor bonus so that experience gained by maxed out units is not altogether wasted. It is generally better to give experience to lower level units, rather than continue to advance units that have reached their maximum level.

=== I tried to trap an enemy with several weak units, but it still escaped. What happened? ===

Most units exert a zone of control (or ZoC). If an enemy moves into one of the six adjacent hexes, the zone of control will prevent it from moving any farther. However some weak units are level 0, meaning they are so weak that they do not have a ZoC. You can still surround an enemy unit entirely with level 0 units to keep it from escaping, but if there is any gap in your ranks, it could escape.

Also, some units have the "skirmish" ability, which allows them to ignore ZoCs.

=== How can I see where an enemy unit can move next turn? ===

During your turn you can click on an enemy unit. Wesnoth will highlight all the hexes the unit can move to in the next turn. This is useful when trying to arrange your units to block an enemy's movement.

=== There's too much luck in this game! ===

Sooner or later, you will become frustrated when your archmage with four 70% attacks misses all four times. This does not mean that the AI is cheating or the random number generator is futzed. It means you are noticing random negative events more than positive ones. During the development of the game, many mathematicians have done sophisticated statistical analysis of the combat system. Likewise, programmers have examined the random number generator. No flaws have been found, so streaks of "bad" and "good" luck should just be accepted as part of having randomness in Wesnoth. A more detailed rational and discussion of the role that randomness plays in Wesnoth can be found [http://www.wesnoth.org/forum/viewtopic.php?f=6&t=21317&start=0&st=0&sk=t&sd=a here].

Since Wesnoth is GPLed, it is possible that a new development team will someday "fork" the source and produce a version more like Heroes of Might & Magic, with less or no randomness. Until then, don't charge with your horsemen against troll rocklobbers at night...

=== The (random unit) is overpowered/underpowered! ===

The development team has spent years tweaking the units in the game. Each unit has had its gold cost, attack types, combat damage, defensive values, resistances, upgrade paths, and other stats carefully scrutinized and loudly discussed in the forum. However, the game code and the units were being modified right up until the 1.0 release, so some unbalanced units may have slipped through.

If you have evidence to back up your claim, search the forum for past discussions about this unit, and then try posting.

=== The (random scenario) is too hard/easy! ===

See above answer about random units.

=== What do the different difficulty levels do? ===

That depends on the scenario. Usually, the opponent will get more money and be able to recruit higher-level units at higher difficulty levels, and you will have fewer turns available.

== Maps, Scenarios and Campaigns ==

=== How do I beat scenario _______ ? ===

If you are stuck on a scenario in a campaign, you'll probably find a walkthrough at [[MainlineCampaigns]]. Or check out the "Strategies and Tips" forum at http://www.wesnoth.org/forum/viewforum.php?f=3

=== How do I download user campaigns? ===
Choose "Campaigns" in the main Wesnoth menu. Then scroll down to the bottom and choose "Get More Campaigns..." or since 1.1.5 there is a "Get add-ons" button in the main menu. This connects you to the campaign server. In the campaign server you can view a list of all available campaigns and download them, as well as posting or deleting your own campaigns.

If you are behind a firewall you may not be able to connect to the campaign server. In this case try to download the campaign directly from the campaign server at http://addons.wesnoth.org/. If you know how to change your firewall settings, then you should open port 15003 (version 1.1.1 and up) or port 15002 (versions 1.1.0 and lower). For added security, you can restrict traffic over those ports to the campaign server's IP address (currently 88.191.12.200).

=== Are there any tools to help me create maps and scenarios? ===
Yes, the game includes a built-in map editor, that you can use to build the terrain maps for your scenarios.

Unfortunately, there's no simple solution for creating the rest of what constitutes a complete scenario or campaign, which is the [[ReferenceWML|WML]] code. There have been some abandoned attempts at creating complete scenario editors such as [[CampGen]], but they are no longer maintained, nor do they work with the latest stable versions of the game.

You should take a look at the [[Create]] section for information and guides that can help you build your own scenario or campaign. Taking a look at how existing content works is also a good idea.

=== What are the .cfg files and how can I edit them? ===

The .cfg files are plain text files, saved with the file extension ".cfg". You can create and edit them using normal text editors; just save the files in correct format.

Please note that some Windows programs like to add a ".txt" extension, so the file is instead of "my_scenario.cfg" saved as "my_scenario.cfg.txt". And then the Windows Explorer will hide the ".txt" extension by default, so you may not notice it.

'''Notepad''': After you create a document, click "File", "Save as..." and select "Save as type: All files". To open the document, click "File", "Open..." and select "Files of type: All files (*.*)". If you open someone else's document, and the end-of-line symbols are displayed as small rectangles, you have to use another editor.

'''WordPad''': After you create a document, click "File", "Save as..." and select "Save as type: Text Document". After the document is saved, close WordPad and remove the ".txt" extension from file. To open the document, click "File", "Open..." and select "Files of type: All documents (*.*)".

Starting with the 1.9.x branch, there is a new IDE for helping User Made Content Authors to easily develop Wesnoth Add-ons. The website and details can be found at: http://eclipse.wesnoth.org

=== I already created an add-on and published it on the server. How can I get translations for the campaign? ===
Just have a look at [[WesCamp]]. This project is the easiest way to get translations for your campaign. All the info you need you can find at [[WesCamp]].

===How do I place an object or unit on my map with the map editor?===
You can't. You need to make a scenario file. There are more details on the [[BuildingMaps|maps]] page.

== Multiplayer ==

===How do I connect to a multiplayer server, when I sit behind a restrictive firewall?===

You have to open outgoing TCP port 15000 - 14997 (depending on the version you use) to play multiplayer games over the internet on the official servers.

===How to find players for multiplayer game?===
Hang around for a while on multiplayer servers and you might find someone to play with. If you observe other people playing you will get informed when someone joins the servers. Maybe you find someone willing to play in the [[Support#IRC|IRC]] channel dedicated to Wesnoth, #wesnoth at irc.freenode.net.

===How to save and load a multiplayer game===

Save the game. Give it a good name, so that you can find it among the other saved games.

Create new game. (Give it a name like "private game for X and Y", so that other players will not try joining it, and you do not have to explain or kick them.) The first item in the map/scenario list is "Saved games", select this. Choose the saved game. Wait for the other player(s) to connect. Start the game.

===How can I make my computer into a dedicated Wesnoth server?===

To setup a dedicated Wesnoth server, you have to compile the game with the "--enable-server" flag, and after you install, simply run wesnothd from the console. This will start the server, listening on TCP port 15000. To compile the server only you can use the flags "--disable-game --enable-server". If you aren't using a linux or mac operating system, there are a few ways you can compile on Windows... [[CompilingWesnoth/CrossCompiling|here is one way]].

'''Note:''' Packages for Wesnoth 1.4 and later include wesnothd by default since it's required by the "Host a network game" option from the Multiplayer menu, which is the preferred option for temporarily hosting a server instance to play in a LAN or privately through the Internet.

===Which versions of Wesnoth can play together?===

You only need to make sure you are using the same minor version number (6 in "1.6.x", 8 in "1.8.x" and so on) corresponding to stable branch releases. If you are using a development release (odd minor version numbers), you must be using exactly the same version number as other clients, to avoid out-of-sync (OOS) issues in multiplayer.

If you are using user-made eras or MP scenarios, all players should make sure they are using the same, latest version of the add-on.

== Translations ==

===Where can I find more information about translating Wesnoth?===
See [[WesnothTranslations]] for a list of currently maintained projects, and methods for contacting their maintainers and volunteering for help, and instructions for starting your own translation if it isn't included in the game already. [http://gettext.wesnoth.org] shows the current progress translations for different game development and stable branches, mainline campaigns and user-made add-ons.

== Other Questions You Have ==

The best way to get answers to less-frequently asked questions is by visiting the official [http://forums.wesnoth.org Battle for Wesnoth forums]. There are plenty of people willing to help. Make sure you read ALL of the forum sticky notes and announcements before posting!

[[Category:Troubleshooting and Bugs]]

FAQ

2015-06-22T14:25:47Z

Anonymissimus: /* What are the system requirements? */

{{FAQ/Translations}}
== General ==

===What is Battle for Wesnoth?===
Battle for Wesnoth is a turn-based tactical strategy game with a high fantasy theme, featuring both single-player, and online/hotseat multiplayer combat.

===What license is the game distributed under?===
The project is distributed under the [http://www.fsf.org/copyleft/gpl.html GPL]. All contributors retain copyright on the portions of the project that they contribute. For more information, see [[Wesnoth:Copyrights]].

===How to get informed about new releases?===
Check the front page of the website.

===A new version is out, but where is the download for [Windows, Mac OS X, etc.]?===
The packages provided, other than the source code tarball, are '''not''' part of the official project. The BfW team only releases the game's source code. Binary executables or applications are always contributed by community volunteers. If not for these volunteers, there would never be any downloads for us to enjoy. The volunteers compile the game and upload it on their own time, and sometimes they cannot do this in a timely fashion (or at all, at times). Although there are usual packagers designated for each operating system, there are times when other members of the community are asked to step in and contribute when the usual people cannot.

Every time a new version is released, the usual volunteers are notified by the project leaders. '''Please refrain from making forum posts asking where your download is''' because it doesn't help anything - the packagers already know, and they will get to it as soon as they can. In the past, the Windows and Mac communities have come together to produce home-grown unofficial builds for the community to use, and the renewed interest in community and learning how to compile is generally a good thing.

===Why doesn't Wesnoth have my favorite feature?===
Because we are building this game for ourselves, to suit our own preferences. We're not building the game for you, in large part because this is our hobby, not our job; whether you like it or not is immaterial to us.
You may wonder, then, what the point is of soliciting ideas, as we do on the forum. We, the developers, have certainly come up with many good ideas on our own, but our players often do as well, and generally ones we don't think of ourselves. If a player comes up with an idea we like, we might implement it. Not because they asked for it, but because of its own merits as an addition to our game.

The beautiful thing about the license our game is distributed under, as compared to closed-source, commercial games, is that if you want that feature badly enough, you can take the code and art of our game and modify it yourself; you are free to re-use any work in Wesnoth, as long as you follow the rules of the [http://www.fsf.org/copyleft/gpl.html GPL]. From this, you can build a game exactly the way that you like. Just don't expect us to build that game for you. Building this game is our hobby, not our profession, and you did not pay us to make it; rather, we are the ones who have paid for it, in time and labor.

===Do you want help making this game? How can I help?===
Yes, we want your help. Whether you're a programmer, artist, musician, writer, translator, level designer, playtester, or just have some great suggestions, you're welcome to contribute. How? You can:
* join the [http://www.wesnoth.org/wiki/Project project]
* share your opinions at the [http://www.wesnoth.org/forum/ Forum]
* talk with us on [[Support#IRC|IRC]]
* [[ReportingBugs|report]] bugs you find with Wesnoth and its mainline content
* update the wiki
* play against other players via the [[GettingStarted#Multiplayer|Multiplayer]] menu
* vote for Wesnoth at your favorite gaming web site
* spread the word!

=== What are the system requirements? ===
'''outdated!'''
We are not completely certain, but an x86 running at 400 MHz with 128 MB RAM should be adequate for versions 1.0.2 and below. For versions 1.1 and up we recommend a computer with at least 1 GHz and 512 MB RAM if you run KDE or Gnome as Windowmanager (The game itself needs about 100 MB RAM). Slower machines will have trouble scrolling large maps or processing AI turns with many units. See the [http://www.wesnoth.org/forum/viewtopic.php?t=7384 forum thread] about minimum and recommended system requirements.

'''update'''
I happened to set up a 1GHz 512MB RAM machine with win xp and a GeForce2 MX/MX 400 with corresponding drivers. This is hardware from about 2000. Scrolling the map is jumpy, but multiplayer in wesnoth 1.12, Isar's Cross, runs fine otherwise. Of course, make sure you reserve as much resources for wesnoth as possible, deactivate animated map and standing animations, and don't have too many AI units on the map. -anonymissimus, June 2015

=== I'm bored; how do I speed the game up? ===

There are several preferences you can change to shorten the time that the AI takes to make its moves. "Accelerated Speed" will make units move and fight faster. "Skip AI Moves" will not show the AI's units moving from hex to hex. Finally, you can turn off all combat animations via the "Show Combat" option on the Advanced tab.

=== My computer is too slow; how do I speed the game up? ===

First, turn off the music and sound effects. Turning off the color cursors will make your cursor respond faster. If scrolling the map is slow, run the game in "Full Screen" mode, not in a window. Turn off combat, map, and standing unit animations via the "Show Combat", "Animate Map" and "Unit Standing Animations" options on the Advanced tab in the game Preferences. You can try turning off halos and combat results, but this might make gameplay more difficult.
For some tips on tweaking the startup, see [[CustomizingStartup]].

== Gameplay and Controls ==

=== How do I learn to play? ===

If you just want to jump right in, start the game and play the tutorial. If you like reading documentation, see [[WesnothManual]]. At any time while playing, you can select help from the menu button (or hit F1). The online help is quite extensive and provides information on terrains, weapons, traits, abilities, units and a good overview of how to play.

=== My unit leveled up but didn't improve. What happened? ===

This is called "After Maximum Level Advancement" or AMLA for short. While most level 0, 1, and 2 units can advance, some cannot. However, some level 3 units can advance to level 4, or even 5. You can see whether a unit can advance further by right clicking and selecting "description."

After a unit reaches the highest level it can get, every time it reaches a new experience threshold (which increases with each advancement) it gains 3 hitpoints and is restored to a state of full health. This is a minor bonus so that experience gained by maxed out units is not altogether wasted. It is generally better to give experience to lower level units, rather than continue to advance units that have reached their maximum level.

=== I tried to trap an enemy with several weak units, but it still escaped. What happened? ===

Most units exert a zone of control (or ZoC). If an enemy moves into one of the six adjacent hexes, the zone of control will prevent it from moving any farther. However some weak units are level 0, meaning they are so weak that they do not have a ZoC. You can still surround an enemy unit entirely with level 0 units to keep it from escaping, but if there is any gap in your ranks, it could escape.

Also, some units have the "skirmish" ability, which allows them to ignore ZoCs.

=== How can I see where an enemy unit can move next turn? ===

During your turn you can click on an enemy unit. Wesnoth will highlight all the hexes the unit can move to in the next turn. This is useful when trying to arrange your units to block an enemy's movement.

=== There's too much luck in this game! ===

Sooner or later, you will become frustrated when your archmage with four 70% attacks misses all four times. This does not mean that the AI is cheating or the random number generator is futzed. It means you are noticing random negative events more than positive ones. During the development of the game, many mathematicians have done sophisticated statistical analysis of the combat system. Likewise, programmers have examined the random number generator. No flaws have been found, so streaks of "bad" and "good" luck should just be accepted as part of having randomness in Wesnoth. A more detailed rational and discussion of the role that randomness plays in Wesnoth can be found [http://www.wesnoth.org/forum/viewtopic.php?f=6&t=21317&start=0&st=0&sk=t&sd=a here].

Since Wesnoth is GPLed, it is possible that a new development team will someday "fork" the source and produce a version more like Heroes of Might & Magic, with less or no randomness. Until then, don't charge with your horsemen against troll rocklobbers at night...

=== The (random unit) is overpowered/underpowered! ===

The development team has spent years tweaking the units in the game. Each unit has had its gold cost, attack types, combat damage, defensive values, resistances, upgrade paths, and other stats carefully scrutinized and loudly discussed in the forum. However, the game code and the units were being modified right up until the 1.0 release, so some unbalanced units may have slipped through.

If you have evidence to back up your claim, search the forum for past discussions about this unit, and then try posting.

=== The (random scenario) is too hard/easy! ===

See above answer about random units.

=== What do the different difficulty levels do? ===

That depends on the scenario. Usually, the opponent will get more money and be able to recruit higher-level units at higher difficulty levels, and you will have fewer turns available.

== Maps, Scenarios and Campaigns ==

=== How do I beat scenario _______ ? ===

If you are stuck on a scenario in a campaign, you'll probably find a walkthrough at [[MainlineCampaigns]]. Or check out the "Strategies and Tips" forum at http://www.wesnoth.org/forum/viewforum.php?f=3

=== How do I download user campaigns? ===
Choose "Campaigns" in the main Wesnoth menu. Then scroll down to the bottom and choose "Get More Campaigns..." or since 1.1.5 there is a "Get add-ons" button in the main menu. This connects you to the campaign server. In the campaign server you can view a list of all available campaigns and download them, as well as posting or deleting your own campaigns.

If you are behind a firewall you may not be able to connect to the campaign server. In this case try to download the campaign directly from the campaign server at http://addons.wesnoth.org/. If you know how to change your firewall settings, then you should open port 15003 (version 1.1.1 and up) or port 15002 (versions 1.1.0 and lower). For added security, you can restrict traffic over those ports to the campaign server's IP address (currently 88.191.12.200).

=== Are there any tools to help me create maps and scenarios? ===
Yes, the game includes a built-in map editor, that you can use to build the terrain maps for your scenarios.

Unfortunately, there's no simple solution for creating the rest of what constitutes a complete scenario or campaign, which is the [[ReferenceWML|WML]] code. There have been some abandoned attempts at creating complete scenario editors such as [[CampGen]], but they are no longer maintained, nor do they work with the latest stable versions of the game.

You should take a look at the [[Create]] section for information and guides that can help you build your own scenario or campaign. Taking a look at how existing content works is also a good idea.

=== What are the .cfg files and how can I edit them? ===

The .cfg files are plain text files, saved with the file extension ".cfg". You can create and edit them using normal text editors; just save the files in correct format.

Please note that some Windows programs like to add a ".txt" extension, so the file is instead of "my_scenario.cfg" saved as "my_scenario.cfg.txt". And then the Windows Explorer will hide the ".txt" extension by default, so you may not notice it.

'''Notepad''': After you create a document, click "File", "Save as..." and select "Save as type: All files". To open the document, click "File", "Open..." and select "Files of type: All files (*.*)". If you open someone else's document, and the end-of-line symbols are displayed as small rectangles, you have to use another editor.

'''WordPad''': After you create a document, click "File", "Save as..." and select "Save as type: Text Document". After the document is saved, close WordPad and remove the ".txt" extension from file. To open the document, click "File", "Open..." and select "Files of type: All documents (*.*)".

Starting with the 1.9.x branch, there is a new IDE for helping User Made Content Authors to easily develop Wesnoth Add-ons. The website and details can be found at: http://eclipse.wesnoth.org

=== I already created an add-on and published it on the server. How can I get translations for the campaign? ===
Just have a look at [[WesCamp]]. This project is the easiest way to get translations for your campaign. All the info you need you can find at [[WesCamp]].

===How do I place an object or unit on my map with the map editor?===
You can't. You need to make a scenario file. There are more details on the [[BuildingMaps|maps]] page.

== Multiplayer ==

===How do I connect to a multiplayer server, when I sit behind a restrictive firewall?===

You have to open outgoing TCP port 15000 - 14997 (depending on the version you use) to play multiplayer games over the internet on the official servers.

===How to find players for multiplayer game?===
Hang around for a while on multiplayer servers and you might find someone to play with. If you observe other people playing you will get informed when someone joins the servers. Maybe you find someone willing to play in the [[Support#IRC|IRC]] channel dedicated to Wesnoth, #wesnoth at irc.freenode.net.

===How to save and load a multiplayer game===

Save the game. Give it a good name, so that you can find it among the other saved games.

Create new game. (Give it a name like "private game for X and Y", so that other players will not try joining it, and you do not have to explain or kick them.) The first item in the map/scenario list is "Saved games", select this. Choose the saved game. Wait for the other player(s) to connect. Start the game.

===How can I make my computer into a dedicated Wesnoth server?===

To setup a dedicated Wesnoth server, you have to compile the game with the "--enable-server" flag, and after you install, simply run wesnothd from the console. This will start the server, listening on TCP port 15000. To compile the server only you can use the flags "--disable-game --enable-server". If you aren't using a linux or mac operating system, there are a few ways you can compile on Windows... [[CompilingWesnoth/CrossCompiling|here is one way]].

'''Note:''' Packages for Wesnoth 1.4 and later include wesnothd by default since it's required by the "Host a network game" option from the Multiplayer menu, which is the preferred option for temporarily hosting a server instance to play in a LAN or privately through the Internet.

===Which versions of Wesnoth can play together?===

You only need to make sure you are using the same minor version number (6 in "1.6.x", 8 in "1.8.x" and so on) corresponding to stable branch releases. If you are using a development release (odd minor version numbers), you must be using exactly the same version number as other clients, to avoid out-of-sync (OOS) issues in multiplayer.

If you are using user-made eras or MP scenarios, all players should make sure they are using the same, latest version of the add-on.

== Translations ==

===Where can I find more information about translating Wesnoth?===
See [[WesnothTranslations]] for a list of currently maintained projects, and methods for contacting their maintainers and volunteering for help, and instructions for starting your own translation if it isn't included in the game already. [http://gettext.wesnoth.org] shows the current progress translations for different game development and stable branches, mainline campaigns and user-made add-ons.

== Other Questions You Have ==

The best way to get answers to less-frequently asked questions is by visiting the official [http://forums.wesnoth.org Battle for Wesnoth forums]. There are plenty of people willing to help. Make sure you read ALL of the forum sticky notes and announcements before posting!

[[Category:Troubleshooting and Bugs]]

HeirToTheThrone

2013-09-10T23:43:39Z

Anonymissimus: /* Scenario 2 - Blackwater Port */

This is a walkthrough of '''Heir to the Throne''', the campaign featuring Konrad.

Some of the information in this walkthrough may be outdated, as the campaign has seen some changes over the years without the respective updates of the walkthrough. It is generally valid and useful, however.

The suggestions herein are mostly based on the ''Medium'' and ''Hard'' difficulty levels. It should be possible to win on the ''Easy'' difficulty level without trying very hard if you are an accomplished gamer. If you feel comfortable with turn-based games, especially ones featuring units moving on a hex map, then you can play the Tutorial and then dive right into ''Medium'' to get a feel for the elements of the game. After you have played a few scenarios and are ready to restart from the beginning (and yes, it is very likely you will have to restart the first time you play Wesnoth), try reading [[AdvancedTactics]]. You should also be familiar with the basics in [[WesnothManual]]—this is a walkthrough, not an exposition of basic game mechanics.

There is a [http://forums.wesnoth.org/viewforum.php?f=39 subforum] for providing feedback on the scenarios of this campaign, with each scenario having its individual thread, where you can post feedback, read other players' comments and sometimes get your questions answered. Note, however, that some of the posts date back to 2004... remember to mind the post dates. The scenario forum threads also have the occasional replay attached to a post (the 'replay' savegame that gets created whenever you complete a scenario).

There are also some personal walkthrough forum posts, such as [http://www.wesnoth.org/forum/viewtopic.php?t=3601 Suggestions for Heir to the Throne walkthrough] and [http://www.wesnoth.org/forum/viewtopic.php?t=4026 Yet another "Heir to the Throne" walktrough]. Finally, [http://www.wesnoth.org/forum/viewtopic.php?t=7064 Ye Compleat Walkthrough to "Heir to the Throne"] is a detailed guide, with illustrations and commentary, to the first six scenarios.

'''Warning - spoilers ahead!'''

== Scenario 1 - The Elves Besieged ==
* Objective: Move Konrad to the signpost.
* Lose if: Konrad or Delfador die or turns run out.
* Turns: 16/14/12 (easy/medium/hard)
* Starting units: Konrad, Delfador.

The orcs as well as your allies will levy a great many troops, you'll soon find yourself between the lines in a huge battle. All those units slugging it out can take quite some time, you may want to try two options on the Preferences dialog, "Accelerated Speed" or maybe even "Skip AI Moves".

This scenario is a "runner" scenario; on turn one, recruit a castle full of fresh recruits, and immediately make a break for it! If you're new to Wesnoth, getting Konrad out of there in one piece will be difficult enough and may require you to start over a couple of times. Hint: don't keep your units all lumped around Konrad, as a large host will attract the enemies' attention.

Terrain dictates two routes to the signpost: west to the druid and then north, or north over the bridge and then west. Either way, you should send Delfador and most of your army straight north. This is a ruse, the sole purpose is to lure the enemy towards the road while Konrad (with only one or two level-1 bodyguards) makes his way towards the exit. There's no chance of winning by defeating all enemies, your troops should perform a skirmishing retreat westwards into the forest.

Other than getting Konrad on his way, the secondary objective you should pursue on this scenario is to gain some experience for your troops. Experience is gained by fighting; once a level of experience is reached, your units will "level up" and become more powerful units. Killing an opponent will give much more experience than just fighting, so you should try to arrange it in such a way that the unit you want to upgrade gets to deliver the ''coup de grâce''.

Now a few words about the units at your disposal. In–game, you cannot check the data of unknown units; if you want to take a peek anyway, check the [http://www.wesnoth.org/units/ Wesnoth Unit Tree].

* Fighters and Archers. Melee and ranged, all elvish warriors are capable of both, it's more a matter of emphasis than an actual distinction. When they level up, most should become Heroes and Rangers, repectively; you'll only need one or two Captains, and probably are better off without any Marksmen: spellcasters will serve the same purpose much better.

* Shamans are minor healers. As a rule of thumb, you should never enter into any scenario without at least one healer. Leveling up a Shaman is somewhat tricky, as they can do only very little damage. If you use stronger units to knock an enemy unit's HP down, you can move your shamans up from behind the lines to administer the finishing blow. As difficult as it is to level up a shaman, it is well worth the hassle. Druids will be standard healers, you want one (and possibly only one) of those as soon as possible. A Sorceress cannot heal at all, but is a powerful spellcaster. At their higest level, both will learn to fly and become very mobile.

* Scouts may seem weak, but there's more to them than meets the eye. While most riders suffer severe penalties in difficult terrain, the elvish variant can cross rivers, swamps and even mountains rather quickly and will usually even receive a reasonable defense modifier. Insofar, they're less like horsemen and more like fast infantry. Whether you employ them in numbers is a matter of taste, however, you should always remember that you have these extremely mobile units at your disposal.

* Konrad, your leader, starts most scenarios at a keep where he may recruit some troops, but that doesn't mean that he should stay there forever: Being always on the map, he may just as well make himself useful. Getting him to level two will earn him a bow as well as the "leadership" ability, both will come in handy time and again.

* Delfador, the Elder Mage, is insanely powerful (at least compared to your other troops for the time being). Mages usually aren't very sturdy, but at level 5 he has so many hit points that you don't have to worry too much about him—he'll survive quite a few counterattacks. Don't overcommit him, but the first few scenarios depend on his abilities to instantly slay nearly any opponent and soaking up some damage that would otherwise kill several of your (still minor) units.

Be careful and don't leave Konrad or Delfador on vulnerable positions at the end of your turns (where many enemies may be able to surround them), especially on ''hard'' difficulty, because all enemies will be particularly aggresive towards them. Remember to use the CTRL-v command to see how far all enemy units will be able to move on their next turn. Click on an unoccupied hex and then move the cursor over an enemy unit to see how far that unit will be able to move.

Early finish bonus: 32 gold per turn.

See also the [http://www.wesnoth.org/forum/viewtopic.php?t=2881 forum discussion].

== Scenario 2 - Blackwater Port ==
* Objectives: Either
** Resist until the end of the scenario, or..
** Defeat the enemy leader.
* Lose if: Konrad, Delfador or Sir Kaylan die or turns run out.
* Turns: 12/12/9 (easy/medium/hard)
* Starting units: Konrad, Delfador, Haldiel.
* Other
** An extra loyal Knight unit as a bonus if the enemy leader is defeated on ''hard''.
** You can recruit horseman units now.

The opening dialog will introduce a new friend, Haldiel, a loyal Horseman. The importance of loyalty is explained in [[CampaignStrategies#The_importance_of_loyalty|Campaign Strategies]].

'''Horsemen'''
:Now that's cavalry as we know it. Their charges can be truly devastating if somewhat suicidal, as your ally will demonstrate soon. Employing charge attacks takes a little getting used to, as it differs so much from ordinary melee. Keep an eye on the "Damage Calculations" until you get the knack of it. 

Back to topic: If you recall units, choose those that have enough experience to be worth the 2 to 6 gold difference over fresh recruits, or who have specific traits that you need. Hole up in the forest on your side of the road (so the enemy has to stand on the plains to face you). Feel free to seize a few villages from your ally, he won't complain. If you have a unit to spare, you may even take the villages next his castle. Matter of fact, this is a prudent move – after all, Sir Kaylan would only use the gold to recruit troops that would steal your experience!

You can also send Haldiel west as fast as possible and attempt to take the village due south of the enemy castle. This will draw some orcs south, reducing the pressure on your actual army and giving you more freedom to shape the battle. However, be careful to not let him get pinned down and killed.

Sir Kaylan will send one or two horsemen to the enemy lines to assist you. Although these horsemen are not under your direct control, they can serve as a distraction if you manoeuver your forces properly, taking the brunt during the enemy's turn to attack.

The first night will be tough, be prepared to lose some units; but if you use the terrain to your advantage, you should have enough of an army left to launch a serious counterattack during the next day. The momentum should keep you going even through the next night and you may soon find yourself besieging the enemy keep. However, the actual objective is merely to survive – if everything fails, you may still retreat behind the swordsmen guarding Sir Kaylans fortress.

There is an early finish gold bonus for killing the enemy leader, however, it will probably be small. In other words: rushing it won't be worthwhile, instead you should play it safe: manoeuver carefully and try to get some experience to those units that need it most. By the end of this scenario, you really ought to have a Druid—that's absolutely vital. Next in line should be an elvish Fighter (make him a Captain) and Konrad, anything else is optional. But the more the merrier as they say.

If you're playing on ''hard'' and manage to kill the orc leader, you will receive a special reward: Simyr, a loyal Knight with the ''intelligent'' trait, will join your army. This might very well be worth the effort, but it will not be an easy challenge. There have been, however, reports from users who have achieved this. You need some good luck distracting most the enemies away from the keep, enough to leave an opening for a few horseman units to charge on the leader during the day (on turn 8/9) in order to finish him off.

Hint for the aim of getting the loyal knight (Anonymissimus): The wesnoth AI moves its units into the direction of the enemy *leader* during its move-to-targets phase. This can be exploited in this scenario by moving Konrad towards Kaylan's keep and leaves the field near the enemy keep open for an attack onto the leader with most of your other units. The leader can be lured out, for instance, by taking the village at 8,21 in turn 7 and moving that unit back in turn 8. Leader moves in there during his turn 8, kill him with Delfador and at least one other high damage dealer (better 3) in turn 9, so have them in range.

See also the [http://www.wesnoth.org/forum/viewtopic.php?t=2929 forum discussion].

== Scenario 3 - Isle of Alduin ==
* Objective: Defeat the enemy leader.
* Lose if: Konrad or Delfador die or turns run out.
* Turns: 34/24/21 (easy/medium/hard)
* Starting units: Konrad, Delfador.
* Other
** A loyal mage named Elrian is hiding in a village near your keep.
** After finding Elrian, you'll be able to recruit magi.

The key to victory is to control the villages, earning the gold you need to recruit or recall troops. You have the option to send the majority of your army west or south with village grabbers going the opposite direction. If you choose to send your army west (recommended) send a scout and an archer south, grabbing alternating villages. Done intelligently they will each grab 1 village per turn until they are near the opponents keep. Be careful of engaging the enemy on the west flank near the hills at night: this is where they shine. Back off to the forests and wait for a more favorable time of day if necessary.

The following strategy works well if you take care of your unit placement. Protect units you cannot afford to lose from multiple attacks at night or when weakened, particularly new horsemen and magi.

First recall or recruit 3 elvish scouts. Send two scouts to the southern villages, and the third to the village to the northwest. Recruit 3 fighters; send one to the south and the other two to the southwest. This works best if one scout is "quick" and the fighter recruited to fill the southeastern hex of your castle is also "quick". If not you may have to modify this strategy. Send Delfador up to the northwest on the first turn to find the mage and send the mage down to the village next to the castle. Konrad should take two nearby villages in the first two turns, because you have no money left anyway.

One of the scouts goes as far south as possible, taking villages and distracting the enemy. This scout is usually destroyed by turn 4. That's OK. The other scout in the south usually has to retreat to survive. You try to take all the villages in the south you can and then reinforce the south slowly and move south. Now your main push is in the west because most villages are there and you need an income of over 20 per turn to recall all of your good troops. I usually use the scout I have sent to the northwest village on the island to take all of the far northwest villages. Delfador can destroy an enemy unit each turn. Horsemen take too long to cross the forest south of your castle but are strong on the western plains during daytime. Send newly-recruited horsemen to the west along with magi. A shaman is useful to the south and later one can be sent to the west.

Approaching turn 10-12, you should have assembled two reasonably powerful forces on each side of the lake. The westerly one usually is based on Delfador and horsemen-mage combos with fighters and archers for ZOC purposes, and the eastern force almost entirely of elves. Remember magi work best against trolls and grunts, and horsemen against archers.

Move south in tight groups, trying not to get too aggressive at night with the west group, until they meet at the far southern end of the island, and assault the castle together.

If you are a new player, you've probably been focusing on game mechanics and how the units and terrain interact. If so, it's time to give serious thought to leveling up some units by allowing them to strike the killing blow. When Konrad or an elven fighter is at level 2, they get the "leadership" skill. When a shaman levels up, they get the "cure" skill.

Hardly any player notices this, but this scenario offers the opportunity for some extra experience at the expense of very little gold. The early finish bonus is 38, but there are 36 villages on the island, so if you control all villages, you only lose 2 gold per turn (or only 1.6 gold, since only 80% can be retained - should be less than 24, since you hardly ever finish more than 15 turns early). So instead of killing the remaining enemies - especially the enemy leader - you might encircle them and reduce their health to a minimum. If you do not attack them in the subsequent turns, they will neither attack nor move, thus regain 2 HP per turn and will eventually be healthy enough to stand an attack of your weaker units. This is a relatively safe way to milk some extra XPs out of them for your weaker units (preferably magi and shamans). While milking level 1 units may not be very rewarding, milking the level 2 leader might easily give 20 extra XPs.

A note about playing with Magi: They are weak units, but become important later in the game. Over the next few levels, you'll want to level at least two Magi to White Magi for later in the game; they have an arcane (or holy) attack which does incredible amounts of damage to the undead. Fire Magi can eventually level up to level 4 Great Magi, which are walking killing machines, and Fire Magi do decent damage to most other units, especially trolls and skeletons. Magi are weak, however, so they need to be guarded by stronger units. Don't let the enemy have more than one attack position on them.

See also the [http://www.wesnoth.org/forum/viewtopic.php?t=2959 forum discussion].

== Scenario 4 - Bay of Pearls ==
* Objective: Either
** Defeat one enemy leader, and resist the other until turns run out, or
** Defeat all enemy leaders (early finish bonus).
* Lose if: Konrad dies or turns run out.
* Turns: 27/24/21 (easy/medium/hard)
* Starting units: Konrad.
* Other
** A storm trident is located on the northwest.

Opening moves: On the first turn, have Konrad recruit or recall some units. Which units, and in which order, is your first tactical decision. If you recruit/recall in pairs, with one fast (6 movement points or more) and one slow unit, then one will be able to move onto the island the next turn, while the other is still wading through the river.

Then, move Konrad to the cage on the island just to the east. This will free some mermen. (How many depends on whether you are playing on Easy, Medium, or Hard.) One of these can go open the second cage, and so on: by the end of your very first turn, you should have at least five mermen in the water.

Watch out: there's one cage far out at sea that's easily overlooked. The first Merman you set free tells you as much, but if you skip the message... Anyway, it is guarded by two nagas. Send two or (at most) three Mermen up there and *do not* fight it out: get the cage first, then kill the nagas with the help of the mermen from that cage. It holds at least four Mermen, on of them an Initiate. The latter may become a healer, try to get her experienced as soon as possible.

Even further north than the last cage there's a trident in the water. It will confer a powerful ranged attack to its bearer. Have a "quick" merman pick it up (who should eventually become a Hoplite).

The remaining mermen should try to hold the sea leaders' recruits at bay. Mermen and nagas both have high defense in water, so combat can be a bit slow and frustrating. Concentrate three or four mermen on a single enemy unit at a time, rather than spreading your attacks piecemeal. Don't push too hard, especially not at night when your attacks are weak. Keeping your loyal mermen alive is more important than the possession of a village, and things will look much better on the next day. If that doesn't suffice, the troops from the deep-sea cage may lend a hand.

It will be nigh impossible for your horsemen and elves to wade to the island to fight the sea leader in time, so eventually your need to do this. The Storm Trident and the Initiate both have magic attacks (70% to-hit regardless of terrain) and should go a long way... you better attack him during the day, even if it means that you need to wait for a few turns.

On land, you have to fight off a wave of orcs and wolves. Your decision is how far west to engage the enemy, though really, you have little choice: You are hindered by the limited recruitment you can do each turn, and how long it takes your elves and horsemen to trickle across the river. Some wolves may reach you in the night, but the bulk of his army won't arrive until daybreak. Press hard during the day, and there will be little left of his army when the night comes.

Careful management of your killing blows should allow several units to get to Level 2. A charging horseman does so much damage it will be easy for the horsemen to get all the kills, but try to get at least Konrad, your loyal mage, and an elven fighter to level-2 (if you haven't already).

The outcome of this battle affects the next scenario you play. If you kill the sea leader you wind up on Isle of the Damned. If you kill the land leader you wind up on Muff Malal's Peninsula. If you kill both, you can choose (and get an early finish bonus).

New players should take the land route to Muff Malal's Peninsula, where you can easily level up many units or collect an early finish bonus. Experienced players or those who are looking for an interesting tactical exercise may wish to consider the sea route to the Isle of the Damned, where you will find a loyal White Mage who *might* join you... if you meet some very tough winning conditions. Either choice will be a battle against undead.

See also the [http://www.wesnoth.org/forum/viewtopic.php?t=3022 forum discussion].

== Diverging campaign path ==
=== Scenario 5A - Muff Malal's Peninsula ===
Scenario objectives: Kill the enemy leader.

This is an easy scenario, and your aim here should be to build up your gold by controlling most villages, while earning experience against enemy forces. The enemy recruits bats to capture villages, and hordes of Walking Corpses to keep you busy. The occasional Dark Adept can be dangerous on Hard difficulty, but is vulnerable to melee attack, especially from knights.

One approach is to recall a few level 2 units supported by a mage. These units build a defensive position in the central part of the map, using hills and forest for cover, and hold off the first wave of Walking Corpses. Mounted troops capture villages in the north and west, and can charge down the flanks at daytime. A merman or two distract enemy bats and capture sea villages. If you can recall the merman that picked up the trident in Bay of Pearls, it will be able to dispatch bats easily on its own.

During daytime, your main force advances to one of the villages in the south-east, where you wait for more Walking Corpses to attack. A level 2 melee unit (eg. Elvish Captain) can use the village defense bonus to survive attacks, and heal between turns. By the time it is low on hit points, it should be advancing to level 3.

You should now control most villages and have some gold, so recruit or recall additional troops. Launch an offensive with your central force, supported by your horsemen advancing at the sides. Don't forget to use Konrad in the attack.

Try to attack with human units only at day, when the undead are at their weakest, and hold the lines with your elves at night.

Early finish bonus for killing the enemy leader.

See also the [http://www.wesnoth.org/forum/viewtopic.php?t=3178 forum discussion].

=== Scenario 5B - Isle of the Damned ===
* Objective: Either
** Resist until turns run out, or
** Defeat all enemy leaders (special bonus)
* Lose if: Konrad dies.
* Turns: 28/26/24 (easy/medium/hard)
* Starting units: Konrad, Delurin (an Outlaw) and two Merman Fighters
* Other
** Thugs, Poachers and Footpads can be recruited in this scenario.
** Moremirmu, a White Mage with a special melee attack can be found in one of the temples in the middle of the map.

Konrad is washed overboard during a storm, but is rescued by two mermen. You start out with 100 gold and cannot recall any units. You are joined by Delurin, a level 2 Outlaw. In addition to Mermen, you can recruit his friends: Thugs, Poachers and Footpads. This is the only time in the campaign that these units can be recruited, but any outlaw units surviving this scenario can be recalled later. Your gold from Bay of Pearls (minus the usual 20% discount) is saved for the next scenario.

Moremirmu is a White Mage with a holy sword which is very effective against undead. He is hiding in one of the three temples, and will join your cause if you find him. Beware: Xakae, a Revenant with a retinue of Walking Corpses, is waiting to ambush you in another temple. Moremirmu and Xakae are randomly placed; the third temple is always empty. Xakae and the Corpses can be a useful source of experience if you have the troops to deal with them.

While your new units might seem weaker than your old troops, they are chaotic like their undead opponents and Thugs and Footpads deal useful impact damage. Use the Footpads effectively to hold your line and the Thugs to deal the main portion of the damage.

Mermen can be used successfully to harass the undead in their rear. Typically the undead responds by withdrawing forces to deal with your mermen. Occasionally this tactic can be used to isolate and trap an undead leader while their forces are busy with your land troops. Don't expect the mermen to survive, though - their pierce damage does very little to the undead, especially at night. Mermen are also useful to hold the many isolated villages scattered throughout the map.

Moremirmu is critical to winning but also quite fragile. He will die quickly if he is attacked by multiple undead.

Early finish bonus for killing both enemy leaders. Moremirmu (and his holy sword) will join you in future scenarios only if both are defeated. There are only a few ways to achieve the early finish. One involves recalling mermen from the previous scenario, including the one with the magical trident, and sending them to kill the southern lich, while land troops attack the other.

The other two center on Moremirmu. Get Moremirmu early, and send him along with a few footmen and thugs north, and use other units to draw fire. Meanwhile, secure the rest of the center of the map from the south. If Moremirmu can finish off the first Lich in time, send that group south -- it takes 10 turns to reach the other Lich, so you'll need to accomplish this by Turn 16! The alternative is to simultaneously send a large force south with Konrad, lure the Lich onto bad ground and surround it.

See also the [http://www.wesnoth.org/forum/viewtopic.php?t=3179 forum discussion].

== Scenario 6 - The Siege of Elensefar ==
* Objective: Defeat all enemy leaders.
* Lose if: Konrad dies or turns run out.
* Turns: 40/32/29 (easy/medium/hard)
* Starting units: Konrad, one veteran unit (typically an elf).
* Other
** A group of thieves/rogues join your party in the first few turns.

Konrad arrives at the southern end of a large map. The island city of Elensefar dominates the center, and the cave of the necromancer Muff Jaanal is far to the north. The orcish warlord Agadla has taken the city. You know what to do!

Your first objective is to retake the city. You could choose to charge across the bridges and fight your way onto the island, taking heavy casualties from the level 2 orcish warriors along the way - but casualties will probably be lower than if you do it the slow way. Or, you can lure the orcs into the water where they are easy to hit. Remember that mermen, especially the one with the Storm Trident, move quickly and defend quite well in water or on the bridges. Whichever strategy you choose, remember that the undead are well on their way to join the orcs occupying the city. Speed is a factor.

Konrad will receive some help from the Thieves Guild. Apparently, an orcish occupation is bad for business. They will either show you a hidden ford onto the island, or attack the north gate after you take one of the island villages. Whether you choose to storm the city, and which aid to accept, depends in large part on how much of a hurry you are in. Every turn, the undead march southward, and you'll have quite a fight on your hands after they reinforce the orcs in the city proper.

After you defeat the orcs, you must fight your way north. Fighting against the undead requires a different mix of units than fighting the orcs. Your mermen are too slow on land. Horsemen and elvish units do reduced damage to skeletons. Here, you need... mages. Lots and lots of mages. And a paladin, if you've leveled a unit that high enough. Expect to spend many turns fighting through the northernmost six hexes. You are fighting in a cave, which slows your units down. Being underground, it is also treated as night for the time of day penalties. Also, don't forget that mages can't take a lot of abuse, especially from melee attacks. You will have to figure out how to use your less effective elvish units and horsemen to shield your mages.

By now, you should have either Konrad or a level 2 elven fighter with the Leadership ability. A unit adjacent to a leader receives a +25% bonus to damage. Likewise, carefully position shamen or white mages in your lines so they can heal wounded units. Two adjacent healers will heal each other.

Early finish bonus for killing both enemy leaders.

See also the [http://www.wesnoth.org/forum/viewtopic.php?t=3224 forum discussion].

== Scenario 7 - Crossroads ==
* Objective: Defeat the north-eastern enemy leader.
* Lose if: Konrad, Delfador or Kalenz die, or turns run out.
* Turns: 37/34/31 (easy/medium/hard)
* Starting units: Konrad, Delfador, Kalenz.
* Other
** There are many enemies hidden in the mountains, placed at random.
** Two loyal units, an elf fighter and an elf archer, join you.

There are two strategies: either to "run for it", or "kill them all". Which you choose will probably depend on whether you want to earn lots of gold, or level up lots of units.

If you choose to run, recall two turn's worth of troops. Most should be level 2, but you should recruit one or two units as sacrifical lambs. Having two healers (who will stay adjacent to each other for mutual healing) is almost a necessity. Move the units in formation (probably in two packs) along the road. Do not be tempted to move units into the mountains. The increased defence is not worth the risk of triggering ambushes. Drive your way to the leader in the northwest, kill them, and reap the early finish bonus.

The second strategy is to methodically destroy all enemy units on the map. Recruit two turns worth of units, and then drive south. Overcome the southern leader, and recruit more troops in his castle. Move back north, moving into every town and through the mountains, in order to trigger ambushes. This strategy is trickier to pull off, but careful management of your kills should allow you to level multiple units. (Just be careful not to run out of turns...)

Note: The first two villages on the screen that you will likely attempt to grab trigger an Elvish Fighter and Elvish Archer to join your party and warn you about the hills. Keep in mind that they, too, are Loyal troops.

See also the [http://www.wesnoth.org/forum/viewtopic.php?t=3281 forum discussion].

== Scenario 8 - The Princess of Wesnoth ==
* Objective: Force Li'sar to surrender.
* Lose if: Konrad, Delfador or Kalenz die, or turns run out.
* Turns: 31/28/25 (easy/medium/hard)
* Starting units: Konrad, Delfador, Kalenz, and one veteran (typically an elf).

Konrad's life now takes an interesting turn, as he meets the Princess of Wesnoth, Li'sar. Instead of dying when you "kill" her, she surrenders.

Li'sar is supported by troops from the Loyalist faction. Even your tough level 2 units make tempting targets for her lawful horsemen; they will charge and probably kill them. Use terrain and position sacrificial level 1 screening units while the sun is high. Likewise, you can try for a quick kill by charging Li'sar with your own horsemen or knights.

This otherwise straightforward battle is enlivened by reinforcements that Li'sar summons on turns 5 and 10. Also, a level 2 Duelist will defend the Princess' honor when you approach her, appearing from the south of your position. You can trigger his arrival by exploring the mountain with an entrance. Capture the villages on the eastern side as you cross the river, and position units to cover the north-eastern plain to prevent Li'sar's mounted units from capturing these villages.

By the end of this scenario, you should have learned a painful lesson in how the computer player targets its attacks...

See also the [http://www.wesnoth.org/forum/viewtopic.php?t=3401 forum discussion].

[hipparchos] Patience is the key here. I send a couple of L2 horsemen north to take the northern villages, then cover your left flank. A couple of mermen swing south to take the southern ones, then cover your right flank. (The storm-trident merman stays on the village next to the mineshaft will deal with the Duellists.) But I put the bulk of my army on the west bank of the river, ''without crossing it''. Let the enemy come to you, because they will be much easier to defeat when they're standing in the river, and that's especially true as the Princess recruits L2 defenders later in the scenario. The bridge is the northern end of your main line, and Delfador can defend it easily with one other strong unit. Only after all the Princess's defenders have been defeated do you cross the river and take her keep.

== Scenario 9 - The Valley of Death ==
* Objective: Survive for 12 turns.
* Lose if: Konrad, Delfador or Kalenz die.
* Turns: 12/12/12 (easy/medium/hard)
* Starting units: Konrad, Delfador, Kalenz, Moremirmu (if unlocked on the ''Isle of the Damned'' scenario).
* Other
** The map contains two holy water objects, useful for attacking undead enemies.

There are two holy water bottles on the map. The unit which picks them up will have their melee attacks be holy for the duration of this scenario. These are especially useful for powerful melee units like Elvish Heroes or Champions which otherwise do little damage to the undead. Or, you could recruit Horsemen and have them grab the holy water. They should easily level to level 2 Lancers or Knights, and maybe even to a Level 3 Paladin by the end of the scenario. As in previous scenarios, mages will be effective against most of the undead enemies.

You'll be facing many level-2 undead. They're all dangerous but two kinds require special attention:
* Spectres (level2 ghosts) are fast in every terrain, somewhat hard to hit, resistant to all common kinds of damage, and have a draining attack. Attacking them in melee is not recommendend, killing them with arrows will eventually work but takes many arrows. They are vulnerable to arcane spells and fireballs, though.
* Walking Corpses: they're slow, they're weak, they're fragile. Usually nothing to worry about, but this time they're many. Hordes. Night of the Living Dead. A strong fighter will easily slay them, but that can become his downfall: an attacking corpse that gets killed makes room for the next corpse to move in and attack... and the next, and the next, and each one gets a few blows. Even a Paladin or Champion will eventually be overwhelmed, taking around ten or fifteen zombies with him. Whether you consider this to be a good exchange is up to you. Incidentally, something similar can happen between Paladins and level-1 Skeletons.

The castle you start in is a well-defensible position, but all enemies arrive at about the same time. Once surrounded, you'll have very little wiggle room or inside tiles for your wounded units to retreat to. Filling the moat with Mermen might work a bit better, but their tridents won't impress the skeletons.

You should consider attacking the southern enemy, then hole up in his castle and the surrounding hills. This increases the distance to the others: their troops will reach you later and they will be strung out, so you don't have to fight them all at once.

If you don't have the money to recruit a large or powerful army, recruit a few Elvish Fighters and send them to the forest north of your castle. Their job is to slow the Revenant for several turns and then die gloriously. Flee with Konrad and the rest of your army to the south-east corner. If you're lucky, the WC horde will be too slow to reach you before the scenario ends. A cowardly tactic, yes—but you'll survive...

If you played Isle of The Damned without killing both Liches, and Moremirmu survived, then he will reinforce you with three White Mage buddies between turns 7-10. You can't recall them after this scenario, so they are expendable.

Another strategy, which requires to have Moremirmu to help you and allows you to kill the three Liches, is to recruit 2 horsemen (or recall their leveled up units) and as many thieves as you can, send each horsemen to gather the bottles of holy water, and kill with them the northern and eastern Liches; don't send them the horseman to the northern Lich too quick, because if you do his army will focus on it, and it won't reach the Lich. Move Konrad, Delfador, Kalenz, and your thieves towards the southeast corner. The thieves be used as a barrier to protect your more important units; place them in woods, mountains or villages(never in plains) as soon as they can, so that the northern and eastern Liches concentrate on them and leave Konrad and his group alone. With some luck you'll kill the northern and eastern Liches around the same turn that Moremirmu appears, and Konrad and his group will survive enough time to have one of Moremirmu's white mages kill the Southern Lich during day time.

[edit: Viper] On medium, I found that I could only make this strategy work by save/loading and by using knights or better for the Litches (as horsemen could not do the job in a single turn even hitting on every attack).

Early finish bonus if you somehow manage to defeat all enemy leaders. If you do, feel free to boast about your accomplishment at the [http://www.wesnoth.org/forum/viewtopic.php?t=3402 forum discussion].

== Scenario 10 - Gryphon Mountain ==
* Objectives: Defeat the mother gryphon and the enemy commander.
* Lose if: Konrad, Delfador or Kalenz die or turns run out.
* Turns: 27/24/21 (easy/medium/hard)
* Starting units: Konrad, Delfador, Kalenz
* Early finish bonus: 24 gold / turn
* Other:
** Killing the mother gryphon is optional, but doing it allows you to recruit gryphon riders in the future.

Konrad starts in the lower left corner of the map. General Robryn, commanding Loyalist troops, is in the upper right. In the middle of the map, surrounded by mountains, is the Mother Gryphon and a few sleeping Gryphons.

If you manage to kill the Mother Gryphon before the Loyalists do, you will have access to gryphon eggs, allowing you to to recruit Gryphon Riders in future scenarios. Opinions differ as to whether their ability to capture far-flung villages, safely lure enemy troops, and ability to pierce the map shroud are worth their high cost. Even if you decide not to attack the Gryphons, the enemy will—and then the wild beasts of the air might decide to attack you.

For a quick victory to earn the early finish bonus, head up the right side of the mountains. To earn experience, head towards the Mother Gryphon, and the enemy will come to you.

== Scenario 11 - The Ford of Abez ==
* Objective: Move Konrad to the north side of the river.
* Lose if: Konrad, Delfador or Kalenz die, or turns run out.
* Turns: 27/24/21 (easy/medium/hard)
* Starting units: Konrad, Delfador, Kalenz.
* Other:
** A storm trident is located in the middle of the river.

The wide Abez river cuts across the middle of the map from left to right, with Konrad starting on the lower right side. Princess Li'sar starts on the lower left, and an orc band is on the north side of the river. Killing the Princess is meant to be impossible: she has plenty of troops as is, and if you actually get near her there will be numerous high-quality reinforcements. Do not even try to attack her, it will be a waste of good troops for no gain. Instead, fill the river with mermen: this is an excellent opportunity to get many of them leveled up.

But first things first: your task is to get Konrad across the river. The chaotic orcs will attack from the north, the Princess's lawful Loyalists will attack from the south, and... a new enemy (alignment: hungry) will be attacking from downstream. All will happily fight each other if they ever meet, but with your army standing right between them in the middle of the river... it will pretty much seem as if everyone was out to get you.

Remember those loyal mermen from in the Bay of Pearls? They should comprise your principal fighting force. Be sure to send one downstream to acquire the Storm Trident there. If you have some of the flying elvish units, they move and fight equally well over land or water. Wait for the Orcs and Humans to get into the water where the mermen have excellent defence while the landlubbers do not.

Even if you have the money, don't recruit for more than two turns, otherwise Konrad might not even make it into the river. The scenario ends as soon as he makes it to the other side (off the beach and onto flat ground) -- by the time he gets there, there will be few orcs left on that shore, Kalenz and Delfador can well deal with them. If you recruit any land troops at all (healers perhaps?), make sure they have at least two moves in shallow water.

This is an excellent opportunity to get your mermen some XP, and you don't really need the early finish bonus.

Early finish bonus for getting Konrad onto dry land.

See also the [http://www.wesnoth.org/forum/viewtopic.php?t=8716 forum discussion]

== Scenario 12 - Northern Winter ==
* Objective: Defeat all enemy leaders (2 of them).
* Lose if: Konrad, Delfador or Kalenz die, or turns run out.
* Turns: 50/40/40 (easy/medium/hard)
* Starting units: Konrad, Delfador, Kalenz, a veteran (knight or mage).
* Early finish bonus: 47 / turn
* Other
** Snow falls on more and more tiles every turn, until the whole map is covered in snow by the time turns run out.

This is a relatively simple scenario. The enemy will mostly raise level-1 wolf riders and orcish archers, plus the occasional level-2 Ogre or Troll. You can field a similar mix of mostly fresh recruits plus a few veterans. Throughout the scenario, the wolves will attempt to seize villages, often bypassing your forces: a few Elvish Scouts behind your lines will come in handy. Alternatively, your loyal Thieves can play hide-and-seek just as well. Don't overrecruit, though: there's only so many units you can actually bring to bear on the enemy. You've got enough time to win this twice, so you may chose to take it slow and milk this battle for experience. You'll still end this with more than enough gold in your coffers.

== Scenario 13 - The Dwarven Doors ==
* Objective: Move Konrad to the entrance of the dwarven tunnels.
* Lose if: Konrad, Delfador or Kalenz die or turns run out.
* Turns: 26/20/15 (easy/medium/hard)
* Starting units: Konrad, Delfador, Kalenz, one experienced Rider, one outlaw unit (if you have any).

You may defeat all enemy leaders if you feel like it, but this won't end the scenario. The sole winning condition is to get Konrad to the entrance of the Dwarven Kingdom. Actually, there are two entrances: the "Great Gates", clearly labeled as such, and a less conspicious side entrance in the north-eastern corner. Only one of these is open, the other is blocked from the inside (determined at random).

You start the scenario with one rider who suggests to scout ahead: that's a good idea, even though you may chose another unit for the task (the game picks the most experienced). If you happen to have a ''quick'' Lancer, it could be a good idea to use it for this purpose, but anyone reaching an entrance will tell you whether it's open or not.

Alternatively, if you played the Isle of the Damned, one of your outlaws will tell you about his uncle who used to have business with the dwarves, hiding in a village along the way (at position [18,24], you'd probably seize it anyway). The uncle is a loyal bandit who joins your troops; he also tells you which entrance to chose, main gate or mine tunnels. It pays off to actually read that dialog.

The most minimalistic approach is to recruit one castle full of cavalry and RUN. The enemies have to cover some distance and cross difficult terrain in order to get in you way -- if Konrad starts running on turn one, he can move past them practically unopposed. It falls to the cavalry to bring up the rear: let them form a line somewhere near the Pillars of Thunedain while Konrad, Delfador and the other walkers keep going. Holding the line for a single turn is enough, then the riders may follow Konrad, leaving the pursuers behind and unable to catch up again (except for the wolves, but there shouldn't be many).

You can still follow this basic principle if you recruit for two turns, adding a healer or two and perhaps some Rangers (their ambushes will stop many opponents). If you recruit for more than two turns, this will become a rather normal battle: your rearguard can no longer disengage, but will have to keep on fighting. There's nothing wrong with that, you can gain quite some experience that way, just don't forget the actual objective.

It's useful to know that moving any unit close to the small lake near the main entrance (any position inside the square between [10, 10] and [15, 15]) will cause an aquatic monster to appear. It will attack anything that moves (including orcs and trolls) and poisons its victims, so watch out.

Konrad needs to get into the mines. Scenario ends with early finish bonus as soon he does so.

== Scenario 14 - Plunging into the Darkness ==
* Objective: Find the dwarves.
* Lose if: Konrad, Delfador or Kalenz die.
* Turns: Unlimited.
* Starting units: Konrad, Delfador, Kalenz.
* Other:
** Secret pasage in south-western part of the tunnel.

In principle, this is quite simple. You cannot recruit and just have to walk down that corridor until you find the dwarves—you can't possibly miss them. You will be attacked by a few bats. They may hurt, that's all. This is mostly a lesson: see how slow Kalenz is in the caves? Notice his abysmal terrain defense? Clearly, this is no place for elves.

Since you're reading this walkthrough, you'll also be interested in locating the secret passage leading to a chest of 200 gold pieces in the southwest. Just stick to the wall, step by step, and you'll eventually find it. However, said chest is guarded by a rather nasty spider: watch out! It's a level-3 beast that poisons and slows.

After you're done with the bats, you can just sit there and wait until your men are healed again. There is no turn limit, after all. Once you found the secret door, do not get in. Step back a bit and the spider will rush out where you can attack her three to one. You should be able to kill her in a single turn, don't worry about getting poisoned—you won't die from poison and there are no other enemies left. However, if you fail to kill her quickly... you saved the game, didn't you?

== Scenario 15 - The Lost General ==
* Objective: Kill all enemy leaders (there are two).
* Lose if: Konrad, Delfador or Kalenz die or turns run out.
* Turns: 64/60/54 (easy/medium/hard)
* Starting units: Konrad, Delfador, Kalenz.
* Other
** A loyal Dwarvish Ulfserker can be found by a merman in this scenario.
** If the allied dwarf leader is saved in this scenario, you will then be able to recruit Dwarvish Guardsman units.

Moving underground is slow, especially for elves. Their fighters and archers are also ineffective against undead. Outriders and slyphs might be worth recalling, if you can afford them. Likewise, gryphons and horsemen are bogged down. Recruit dwarves for speed, and mages to back them up. (However, a Gryphon can pass the small pond quickly, and there are four towns on the other side.)

You are fighting Lionel, a former general turned Death Knight, who starts trapped in the south. To the west is the usual orc/troll force. In the north is a dwarven ally, although if you are too slow they will be overwhelmed by the orcs.

Dwarven fighters do well against the undead, while the Thunderers do best against the orcs and trolls. If you choose to go for money, rush troops both south and north, reinforcing the native dwarves and triggering the appearance of the undead. If you choose to go for experience, ignore the undead until you have killed the orcs, then return en masse to destroy the undead. Don't take too long, as Lionel will break forth on turn 20.

There are two ways to get to Lionel: an entrance opens in the pond on turn 19/20; and walls collapse when units move into tiles just south of the sign that says "Guest Quarters", regardless of when this happens.

If the dwarf leader survives (and you actually reveal him), Dwarvish Guardsman will become available. It is easy to underestimate the importance of these units. Their defensive capabilities can be greatly appreciated towards the end of the campaign, especially in the last two scenarios.

Note: If you recall/recruit a merman and send it to the pond, then have it go to the whirlpool, it will arrive in a hidden cavern with a friendly ulfserker. Once your merman returns to the whirlpool through the other end, it will carry the ulf with it.

== Scenario 16 - Hasty Alliance ==
* Objective: Defeat the enemy leader.
* Lose if: Konrad, Delfador, Li'sar or Kalenz die or turns run out.
* Turns: 33/30/27 (easy/medium/hard)
* Starting units: Konrad, Delfador, Kalenz.
* Early finish bonus: Killing enemy leader + 200 Gold from Li'sar

Li'sar is about to attack, when you are surrounded by orcs and trolls. She joins forces with you to defeat the troll leader, bringing her Royal Guards and 500 gold worth of allied troops to the struggle.

Your greatest challenge will be to survive the first few turns, as the death of any of Konrad's companions will end the scenario.
Once you have defeated the first wave, it is relatively easy to finish off any remaining trolls and move north to the troll leader. Try and encourage your allies to go first and take the hefty damage from the Level 2 and Level 3 trolls, while your mages and dwarves get the experience for killing blows.

The way I did it was to recruit a keep of thieves (the cheapest unit) and move Delfador and Kalenz out of the way. Then my allies were able to send help over so that I could get 'real' units on my second turn without suffering casualties. One thief survived and I got a Rogue with 36/56 XP by the end of the scenario! -CountPenguin

== Scenario 17 - The Sceptre of Fire ==
* Objective: Capture the Sceptre of Fire with Konrad or Li'sar.
* Lose if: Konrad, Delfador, Li'sar or Kalenz die or turns run out.
* Turns: 50/45/35 (easy/medium/hard)
* Starting units: Konrad, Delfador, Kalenz, Li'sar.
* Early finish bonus: n/a
* Other:
** 300 gold gift from Li'sar.
** Milk this level for experience as there is no early finish bonus.
** Randomly generated map.

The map changes each time, so if you're save-scumming, be sure to checkpoint right after the scenario starts, and replay once you know where the Sceptre is.

There's three or four enemy leaders, depending on difficulty. The map is randomly generated; there's no telling how many villages there are and where... but more often than not, it's something like 25 villages and most will be placed where you can seize them early. The scenario certainly feels as if you're in for a major underground struggle, but the enemy leaders have little money to begin with and -usually- they won't have much of an income either.

Usually there's two large tunnels going north, and quite often you meet little resistance in one, and quite a lot in the other -- though the latter still doesn't qualify as tough. You can gain quite some XP in the contested tunnel, just form a shieldwall with (mostly) guardians, play it safe, and you can level up some 4-8 dwarves. It's a good idea to station Kalenz here, his faerie fire will help a lot against the occasional lvl-3 Troll.

Meanwhile, The Princess, Delfador, one healer and several of your better dwarves should move up the less contested corridor and scout the map. The Scepter usually is somewhere about 2/3rds up the map. You may encounter the occasional enemy... it's alright to buzz off in all directions, but make sure that everyone has a line of retreat and may receive support within a turn or two.

The scenario ends as soon as Konrad or the Princess gets to the scepter. You may delay this a bit in order to milk a few more XP, but there's not that many more to be gained by then. All things considered, it's better to let Li'sar have the scepter -- she'll be with you until the end, she has no ranged attack, and while Konrad will often be held back by recruiting, Li'sar can be in the frontline from turn one.

Note: When the earth rumbles, something actually happens. There are lava chasms in various places, and these grow when there is a rumble, so keep your units away.

== Scenario 18 - A Choice Must Be Made ==
* Objective: Defeat either of the leaders.
* Lose if: Konrad, Delfador, Li'sar or Kalenz die or turns run out.
* Turns: 33/30/27 (easy/medium/hard)
* Starting units: Konrad, Delfador, Kalenz, Li'sar.
* Other:
** The next two scenarios are three different routes to the Elven kingdom, depending on the enemy leader you kill:
*** Northern (Orcish) leader: [[#Scenario 19A - Snow Plains | The Snow Plains]] where you can get the Flaming Sword (15-4, magical), followed by [[Scenario 20A - Home of the North Elves|Home of the North Elves]].
*** Southern (Undead) leader: [[#Scenario 19B - Swamp Of Dread|The Swamp Of Dread]] where you can get the Void Armor (high resistance to blade, pierce, impact) , followed by [[Scenario 20A - Home of the North Elves|Home of the North Elves]].
*** If you take a merman east on the river to the edge of the map, you will brave [[Scenario 19C - The Cliffs of Thoria|Cliffs of Thoria]] which (used to be) an insanely difficult battle where you can find a loyal Sergeant (may become a level-4 leader). It will be followed by [[Scenario 20B - Underground Channels|Underground Channels]].
** Simply decide for one direction and block the bridge in the other direction unless you want to fight on two large fronts.
** First real chance to level gryphons.

Scenario objectives: Kill either leader.

Going south is the easiest way: the Orcs coming from the north may only cross the river at the bridge, a choke-point that's easy to block. In fact, a determined attack may defeat the undead before the bulk of the Orcs even makes it to the bridge. Fighting the Orcs in the hills will take longer while the undead can walk through deep water or fly over it, crossing the river wherever they like.

Going south will also the most prudent choice when considering the possible goodies: currently, Li'sar goes into battle wearing lingerie. While a magic sword or a loyal leader might come in handy, you don't need them as badly as the Princess needs a suit of armor.

The undead need to be dealt with even if you don't want to kill their leader. Delfador, Kalenz and Li'sar all have undead-killing ranged attacks (you ''did'' give her the scepter, didn't you?) — add two more Mages (one of them a healer) and three dwarfish Steelclads as bodyguards. Recruit those on turn one and move them to a position where they may receive the Chocobones' attack by dusk. You need at least steelclads in order to survive their charge. However, after the Chocobones are gone the remaining undead ought to be manageable even if you don't throw any more troops that way (though you may do so if you're after the undead and want this to be finished quickly). You may need a few turns' rest before you can tackle the Death Knight, but eventually your spellcasters should dispose of him quickly.

In order to hold back the Orcs, a few elves plus a healer are enough to secure your end of the bridge; the Orcs will be reluctant to attack even level-1 archers during the day, and if you employ more and better troops (like, level-3 loyalists in the woods and a few mermen in the water) the Orcs may not even attack at night. There's not much experience to be gained that way, though. If you want to actually fight the Orcs, you should get to the other side and meet them there. There's plenty of mountains, an excellent opportunity to get some more experience to your dwarves (you will have good use for high-level Dwarves later on). Dwarves, Gryphons and Orcs all have high defense in the mountains, so fighting will be slow.

It will be a long walk to the northern leader even after you rubbed out his army. You might consider an assassination: send like 4-6 suicidal gryphons to his keep. Bonus points if you have a Silver Mage (teleport!). Of course, you can assassinate him without defeating his host first. just wait until his army is too far away to turn back and help him.

Talking about Gryphons... this is the first time that you can really use them. Gryphons alone won't really impress the Orcs, not even when supported by leaders and healers (they're level-1 units, after all). They may however seize a few villages, harass and distract the enemy, track down wounded units and so on. You should certainly get a few.

They must have changed this scenario. As of v 1.9.5 at medium level it's absurdly easy. I recruited just one keep (two paladins, two mages of light, and two griffons). Then charged for the undead leader (South) and wiped him and his evil minions out by the end of turn 9. The griffons didn't even get in the fight. The Orcs hadn't even reached the river bridge. ~ Sojourner, 4/16/11.

== Diverging campaign path ==
=== Scenario 19A - Snow Plains ===
* Objective: Defeat the enemy leader.
* Lose if: Konrad, Delfador, Kalenz or Li'sar die or turns run out.
* Turns: 43/40/37 (easy/medium/hard)
* Starting units: Konrad, Delfador, Kalenz, Li'sar.
* Other:
** Obtain the Flaming Sword.
** Li'sar will tell you about her relationship with her mother.

The main feature of this scenario, as its name suggests, is the terrain. Both armies will be slowed down by the snow. You may try recalling thieves and elves, who are not slowed down as much as other types of units. Another good choice is horsemen (Knights, Paladins, Lancers), which will have a field day, given that the enemy tends to scatter some of its units throughout the map where they will be sitting targets.

You can find the Flaming Sword—a remarkable weapon of type melee-fire, magical, and with damage 15-4—on the great tree at [29,9]. You can equip it to one of your fighter heroes (Konrad, Kalenz, Li'sar) or any unit from the Elvish Fighter line, or to Paladins. A good idea is to give it to the unit you like to use the most in your front lines (but not to the same person with the Sceptre of Fire).

The Orcish leader will have a good flow of income, so once you gain control of the map, you can milk the battle for experience, in case any of your units need it.

=== Scenario 19B - Swamp Of Dread ===
*Objective: Defeat the main enemy leader (Lich Lord at the SW corner)
*Bonus Objectives: Defeat all the minor enemy leaders (4 Death Knights)
*Lose if: Konrad, Delfador, Li'sar or Kalenz die or turns run out
*Turns: 33/30/27 (easy/medium/hard)
*Starting units: Konrad, Delfador, Kalenz, Li'sar.
*Early finish bonus: 26/turn (on Medium difficulty)
*Other:
**Void Armor from one of the enemy leaders.

The swamp of dread isn't all that dreadful. This is a 5-castle map and there are lots of undead, but they are mostly levels 0 and 1 - nothing like Princess' Revenge. The terrain is unfavorable (swamp and sand, but hampers the Undead as much as you; and if you have a preference for Gryphons or Merman, the mobility advantage will be yours.

The swamp is good terrain for your Mermen. Those with attacks that hurt the undead (the ones with Storm Tridents, Netcasters, Priestesses...) or any level 3 unit can make quite a difference. However, be aware that the campaign is coming to an end and you'll probably have little use for Mermen in the following battles; so while the Mermen may well lend a hand, any experience they gain will effectively be wasted. (However, the next two levels do include rivers, so if you really insist you could still use Mermen later.)

One of the Death Knights (chosen randomly) drops the Void Armor when killed. The unit that picks it up will gain high resistance to physical damage (50% blade, 40% impact and 40% pierce, instead of whatever previous values they had). Since Li'sar is very vulnerable to precisely those types of damage, you should probably give her the armor. You might consider keep her in the center at first so she doesn't have to walk across the whole map if the armor appears at the other end. Note, however, that by the time you get the armor you're probably close to clearing the level anyway, so better to think of it as an end-of-scenario perk rather than an intermediary objective playing the scenario.

Some of the Lich's power seems to be tied to the death knights; killing all four will hurt the Lich for about half its hit-points.

Early finish bonus for killing all 5 enemy leaders.

See also the [http://forums.wesnoth.org/viewtopic.php?f=39&t=10269 forum discussion].

=== Scenario 19C - The Cliffs of Thoria ===
* Objectives:
*# Make it to the end of the river, to the east.
*# Reach the cave with Konrad.
* Bonus Objectives: Rescue the loyal Sergeant.
* Lose if: Konrad, Delfador, Li'sar or Kalenz die or turns run out.
* Turns: 55/50/45 (easy/medium/hard)
* Starting units: Konrad, Delfador, Kalenz, Li'sar, a Merman veteran.
* Early finish bonus: 27 per turn
* Other:
** Loyal Sergeant on SE corner island.
** A storm trident is located near the first two islands.
** You find small amounts of gold on each drake base you conquer.

After a little spat between Kalenz and the merman you use to go east, you'll head for the Cliffs of Thoria. You'll find a long water level full of derelict vessels of the Queen. You'll also meet a Drake. After some conversation you discover that the Queens' forces attacked the Drakes, and now the Drakes will stop you from going forward. Since you have to move forward, you'll have to fight them.

There are a number of small islands on this map with Drake bases. Each base will produce one Drake every few turns until one of your units occupies the base. This means that although the drakes may run out of money, they will never run out of reinforcements. In order to win this, you need to kill them faster than they spawn new recruits. No easy task.

Further, if you find that you can't win in a direct assault and want to bypass the drakes by going through the swamps, you'll discover very powerful undead enemies guarding the shoreline. They won't move, but any casualty will be immediately replaced by a new unit. Clearly, that area is cursed. Just avoid the dark blue water. It's impossible to get into the swamps, any attempt will be a waste of time.

There is an opportunity to pick up a wonderful loyal unit, although you may wish to skip the challenge if you don't have good gold reserves and a sufficient number of leveled-up mermen.

Among the choices presented in the previous scenario, this map has historically been intended to be the hardest one of all. However, as of version 1.10.x, this map has been made significantly easier. The main difference is that now the drakes come out at a slower rate from their bases, and they are much more passive in general. With careful strategy and by progressing steadily through the map—not moving your gryphons ahead too quickly—you should be able to beat it without a lot of pain. At any rate, this scenario is no longer the monumental challenge it used to be.

Hire many gryphons and Merfolk. Since each base creates a unit every few turns, to destroy a base you have to kill its occupant or wait until it flies towards one of your units, and then move a unit onto the base as quickly as possible, before a new drake comes out of it. Since Merfolk can't move onto mountains, you'll need gryphons for that.

Drakes are vulnerable to piercing and arcane damage, so elvish arrows can be useful, as can your healers as spellcasters, but don't get too many landlubbers—most of the fighting will happen in or over the water. Level-1 mermen will either die quickly or level up; high-level mermen will wreak havoc on the drakes. However, you need a good many level-2 mermen to begin with. Rookies alone cannot maintain the constant pressure you need, and the turn limit is short enough as it is.

When you finally make it to the far side, you'll be told that the waterfall is impassable: you need Konrad to reach the marked "cave entrance" in the middle of the northern edge of the map. Start walking early, he'll take a while.

A loyal leader can be found on the island at the South-Eastern corner of the map. He's badly hurt and poisoned, but you will probably have the time to clear the surroundings and level him up using the undead swamp guards.

Comment: The decreased difficulty combined with the easily available XP in shape of the undead guards unbalances the rest of the campaign badly. If this is not intended, choose another road.

== Divergent Campaign Paths ==

=== Scenario 20A - Home of the North Elves ===
* Objectives:
* Konrad must reach the Lintanir forest, at the East of the map, and hold that position until a turn is over.
* Lose if: Konrad, Delfador, Kalenz or Li'sar die or turns run out
* Turns: 18
* Starting units: Konrad, Delfador, Kalenz, Li'sar
* Early finish bonus: 47 Gold per turn
* Other:
** Your base will be dismantled after the first turn

You reach this scenario from either [[Scenario 19A - Snow Plains]] or [[Scenario 19B - Swamp Of Dread]].

This is a very large map with some interesting challenges. First, Konrad needs to move all the way across to the right side, and if you're playing on Medium or Hard, you don't have many turns to waste. Second, Fog of War is turned on, so you won't know where the enemy is until you blunder into them.

However, even in the fog you can see the terrain, including the enemy keeps. The Orcs start in the North central part of the map, while the humans begin in the South-East. What you can't see are the large hosts of level-3 units standing near their respective camps: these are the armies, and *they will not move* unless someone walks into their striking range. Getting at an enemy leader will be difficult indeed, but if you're content with moving past the armies you'll only have to cope with the level-2 vanguards seeking each other.

You start with up to 3 loyal units which can move six or more hexes per turn (provided you kept this many alive), in addition to the 4 heroes (Konrad, Li'sar, Kalenz and Deflador). You many recruit an additional encampment of more troops (i.e. 6 more); it's probably best to get only riders, be they human, elf or gryphon. Most of them should be level-2 at least. If you want to bring a healer, get the fastest on your roster (a quick Elvish flyer, perhaps?) and make sure it's spawned at the right side of your keep.

There is some dialogue to remind you that the winning condition is to move Konrad into the forest, while keeping Li'sar, Delfador and Kalenz alive; everyone else is "not important". During the game, some Elvish riders will show up and happily demonstrate how sacrificing a single unit can keep many others safe; they do it so well that you probably don't need to sacrifice any units of your own, but now you know how it works.

The dialogue makes you expect a large battle between Humans and Orcs, but no one tells you that the Elves (who have a keep in the woods) will also recruit a large force, and attack anyone in sight; you'll probably see your first Human warriors much later than you'd expect and find that they're busy enough fighting the elves. So you only really have to deal with the Orcs; once you're confident that they can't get at Konrad anymore, he can move on pretty much on his own. Your troops may turn around and fight the remaining Orcs, or join the Elves and steal a few kills there, or whatever. Have Konrad stop short of the forest to give your troops more time for fighting if you feel like it.

Delfador will tell you when Konrad enters the domain of the Elves, but the scenario won't end then: you need to finish your turn and let everyone else have one last chance to attack your troops. If Konrad is still alive at the beginning of your next turn, you've won.

See also the [http://forums.wesnoth.org/viewtopic.php?f=39&t=10270 forum discussion].

=== Scenario 20B - Underground Channels ===
* Objective: Find the exit from the underground and move Konrad to it.
* Lose if: Death of Konrad, Delfador, Li'sar, Kalenz, or turns run out.
* Turns: 80/70/60 (easy/medium/hard)
* Starting units: Delfador, Kondrad, Li'sar and Kalenz.
* Early finish bonus: 54 per turn

You start at the far South West of a large map, consisting of mostly cave, river and swamp areas. In the North West is a friendly Wose leader who will send a few level one Woses, and at the far North East is the entrance, and some friendly elvish units. In the middle is an ancient Lich who recruits level 2 and 3 undead, and in the South East is a small group of Saurians.

This level is relatively easy, especially with the high-level Mermen you should have from the Cliffs of Thoria. You can recruit on keep of level 2 and 3 Mermen and Dwarves, and either run North and then East for a quick finish, bypassing most enemies, go East and then North, farming some experience from the Saurians, or slowly kill every enemy on the map before continuing. Be careful if you choose to fight the undead though, as the ancient Lich can kill most of your units in one turn, and his recruits, though not numerous, are powerful. If you choose to fight the undead, the mermen who got the tridents in previous scenarios, as well as any Mermaid Priestesses or Diviners will be extremely useful.

See also the [http://forums.wesnoth.org/viewtopic.php?f=39&t=20315 forum discussion].

== Scenario 21 - The Elven Council ==
This is a cut-scene furthering the storyline. No combat takes place.

== Scenario 22 - Return to Wesnoth ==
* Objective: Defeat all enemy leaders: 2 Loyalist Generals, 1 Orcish Warlord.
* Lose if: Konrad, Delfador, Li'sar or Kalenz die or turns run out.
* Turns: 31/28/25 (easy/medium/hard)
* Starting units: Konrad, Delfador, Kalenz, Li'sar.

Three Halbardiers appear as enemy reinforcements in the lower southeastern corner of the map when you slay the nearest general, Josephus (just South of your encampment). The bridge across the river is a good place to establish a defensive position, since attackers have to use the beach and water hexes to attack.

You can use the forests to your advantage: Elven troops are best in forest, while the Loyalists and Orcs are seriously slowed by the trees. On the other hand, nobody said your enemies will be that interested in frolicking in the forest when they have more accessible enemies outside of it.

How about Gryphons? Your enemies will be recruiting level-2 and level-3 units, and the Halbardiers are level-3, so relying on a force of Gryphon riders, or even Gryphon masters, will probably not work out too well. However, a pair of Gryphons (especially quick ones) can work great for village captures, doubling as an effective diversion, especially with respect to the Halbardiers. Watch these heavy-hitters comically wading through the thick brush of the South-East forest as you fly circles around them.

Your enemies aren't very rich, so while their recruits are powerful - they're also few in numbers. This means their defensive formations will have gaps. Add the fact that, except for the Goblin Knights, your enemies are on the slow side, and you find that using mounted units could be opportune. The downside for these is the Halbardiers' first strike: A lancer or Knight taking ~38 damage before touching his enemy is not a pretty sight. Take these out with your heroes instead (Delfador, Kalenz and whoever has the scepter), or units with ranged attacks.

See also the [http://forums.wesnoth.org/viewtopic.php?f=39&t=10272 forum discussion]

== Scenario 23 - Test of the Clans ==
* Objectives: Either:
** Defeat all 4 enemy leaders (Grand Knights), or
** Kill (25/35/50) enemy units in total (on Easy/Medium/Hard difficulty)
* Lose if: Konrad, Delfador, Li'sar or Kalenz die or turns run out.
* Turns: 53/50/47 (easy/medium/hard)
* Starting units: Konrad, Delfador, Kalenz, Li'sar.
* Early finish bonus: 54 Gold per turn (on Medium difficulty)

This is a large map against mostly Knights, Lancers, and Bowmen. The map is mostly open plains, which is an ideal battlefield for mounted units. The easiest way to complete the scenario is to keep all your units in one group and take them en mass to the enemy. Fast and powerful units like Grand Knights, Lancers or Paladins are important. Units with pierce attacks (Archers, Shydes, Knights) will deal high damage to the mounted enemy units (which have low pierce resistance).

Expect heavy losses from the charge attacks, but don't fret, because this is the second-to-last scenario. You'll want to finish this scenario quickly to get a nice gold bonus for the next level.

Reportedly, one way to win is to gang up on Bayar with fast units while attacking the south-eastern leader with the rest of your army.

If you want to have a long field battle, you can put groups of Dwarves or Elves in the hills. The enemy will tend to attack the hills, thus giving you some advantage. Hills also make a relatively safe haven for healing your mounted units. Try to kill the South-Eastern leader early so you don't have to divert so many of your resources to the South flank.

If you want to defeat all the clan leaders before killing the maximum allowed number of units (which ends the scenario), recruit a castle of Healers, then recruit a good force of Gryphon Riders. Grab as many villages as is safe, and then position your Gryphons on the deep water in the lake. The next castleful of recruits is your main army and two more Gryphon Rides. March this South, take out the South-Eastern leader, then send the two Gryphons to the group in the lake.

As soon as the majority of the North-Western leader's troops move away from him, assassinate him with your Gryphons. He should die in 1-2 rounds of attacks, assuming you don't lose too many of your troops. In the South-East, recruit a couple of castles' worth of Gryphon Riders and send them west to take on the South-West (Black) leader, all the while keeping your main force just out of range of attackers if at all possible. As your Gryphons cross the river on the offensive, the AI usually moves troops back in to defend with. You should be able to outrun these. Converge all the Gryphons you have left on the middle leader (Purple). I won around turn 25, giving me around 1600 gold to start the last scenario.

An alternative strategy for defeating the enemy leaders relies on Li'sar being equipped with both the Scepter of Fire and the Void Armor. This makes her very difficult to hit and very effective against the mounted units (they have no ranged attacks, plus, if they try to lance her they're up against 26-4). What's more, the AI will tend to ignore her: Individual units will tend to not approach her, and groups will go after her escort if she has any. This means she can mount an effective attack together with a very small escort on the South-Eastern leader right away; and after that, the escort can pretty much leave her to go after the Black leader in the South-West alone. In the mean time, A force of Knights or Gryphons might go forward to dispatch the North-Western leader. Then whoever i's left converges on Bayar in the West.

See also the [http://forums.wesnoth.org/viewtopic.php?f=39&t=10273 forum discussion].

== Scenario 24 - The Battle for Wesnoth ==
* Objectives: Defeat Asheviere (thus claiming the throne for Li'sar)
* Lose if: Konrad, Delfador, Kalenz or Li'sar die or turns run out
* Turns: 60
* Starting units: Konrad, Delfador, Kalenz, Li'sar, as many Grand Knights as you defeated in the last map
* Early finish bonus: 46 gold per turn (and what's that good for, exactly?)

One good strategy for this scenario is to set up a defensive line around your fort, and let the enemy come to you. You'll want to make sure the units on your front line can survive the beating they receive for at least one turn, after which you rotate them with freshly healed units. Don't attack the attackers if it means your unit won't have enough HP to survive the next thrashing. Three or Four healers will be needed behind the lines, and keep them fully occupied (remember that healers will heal every unit adjacent to them for 8 HP. They're like walking sets of 6 villages).

For front-line units, Dwarvish Guardsman, even Level-1, are excellent; they'll take a good beating but not lose too many HP because of their steadfast attribute, on top of their basic resistance to Pierce (read: lance) attacks. Because they don't lose many HP, they'll also heal quickly. Only attack the enemy if no HP will be lost. Guardsmen can throw a spear at the attacker on every turn if the attacker has no ranged attack.

Other units that are good for the front line are any unit with more than 50 HP. Elvish Marshals will make your Dwarvish Guardsmen or Stalwarts even more awesome. Dwarvish Lords have an incredible 79HP and can dish it out back to the enemy. Unfortunately, after a good thrashing, these units will take a long time to heal back up because of the large number of HP lost.

If you have any Assassins, rotate them up and down the line, poisoning enemy units. The enemies have very few villages available to them in your vicinity, so with three Assassins you can poison half the army until the enemies have a bunch of level three units walking around with 1HP each.

Once the enemy has no army left, you can just wander up to Asheviere and discuss her resignation over a cup of hot tea. Asheviere has exactly 48 HP, so three hits of a 16-damage weapon, like the Scepter, or four 12-damage hits, is enough for the kill. Or you could surround her with Elvish Shamans and get the last little bit of fun juice out of this game.

A quick assassination can even be performed by Master Gryphons or even sometimes Gryphon Riders: Recruit six of them, right on Turn 1, and send them South. You'll
easily elude the forces of the Eastern general and reach the river (or just past it). Moving in for the kill, however, might prove more difficult than you think - unless you've used an effective distraction. Sending out six-packs of Knight recruits each turn works well. Asheviere herself will not have many troops surrounding her for protection, and might actually be stupid enough to leave her castle to attack your Gryphons. One has to wonder how she's held on to the throne this long with such a poor sense of judgement. You'll probably want to approach her from the South-West, as right South of her is the bridge on which the loyal Weldyn troops will be coming to get you.

Using this strategy it is possible to win within 6-7 turns, without any significant losses. If, however, you've not distracted well enough, Asheviere may divert up to half of her forces to get your Gryphons. But in this case, again - congratulations, you've won: You should have still about 20 living Knights to storm the city with, while too many of her troops are stuck finishing their roast Gryphon sandwiches.

Of course, in both of the above cases you would be relying on a good bonus from [[Test of the Clans]], which should be enough to win this scenario in any which way.

Another humorous brute-force way to win this battle is by relying purely on the diversion tactic mentioned above: An all-Knight rush. Knights are quite possibly the only Level-2 unit you can ever recruit in the mainline campaigns; with roughly 1,500 Gold from the plains battle, just send out loads of Knights to massacre the enemy with suicidal attacks. Just make sure to keep your heroes out of harm's way... It'll be a very bloody, but relatively short, win.

See also the [http://forums.wesnoth.org/viewtopic.php?f=39&t=10271 forum discussion].

== Scenario 25 - Epilogue ==

[[Category:Campaigns - Walkthroughs]][[Category:Campaigns - Heir to the Throne]]

WesnothRepository

2013-07-01T16:21:19Z

Anonymissimus: remove a reference to subversion

{{Compiling Wesnoth}}

The Battle for Wesnoth code base is stored in a version control repository. Version control allows the entire dev team to edit files concurrently. The software tracks revisions, stores a record of all edits, revents simultaneous editing from causing clashes. All changes are stored in the version control repository.

When a release is planned, the current set of the files in the repository is frozen, given a release number, and shipped out to the world at large. Then, as files continue to be edited by the developers, the repository code advances past that point. The repository (or "repo") version is by definition the most up-to-date version of the code.

The Wesnoth repository uses Git and lives at https://github.com/wesnoth/wesnoth-old

== Git ==

Git is the most widely used open-source version-control system. You can learn more about it at the Git home page, http://git-scm.com/.

Git replaced Subversion as Wesnoth's version control system in March 2013. Subversion had itself previously replaced an older program called "CVS" or "concurrent versioning system" in 2005. These earlier systems have left a few traces in the version history which you might encounter; some older documentation and a few files refer to them.

== Browse the code ==

There are currently two main streams of development: trunk (1.11.x) and stable branch (1.10.x). Most other branches are only used for a short time to do some testing without disturbing the main development. You can use your web browser to navigate through the source code:

https://github.com/wesnoth/wesnoth-old

== Download ==

To check out a read-only copy into a directory called ''wesnoth-code'',

git clone git://github.com/wesnoth/wesnoth-old.git wesnoth-code

== Commit access ==

For commit access, you must have a developer account on GitHub, it must be registered as part of the Wesnoth group, and you must check out with:

git clone git@github.com:wesnoth/wesnoth-old.git wesnoth-code

== Update ==

Do this from inside the ''wesnoth-code'' directory

git pull

== Reviewing your changes ==

Before committing, it's always wise to run

git diff

and look at the output. Some kinds of mistakes that are hard to see embedded in all the code you have modified are more easily spotted in the isolated diff lines.

== Generating patches ==

Under Git on a Unix-like operating system, you'll typically do

git format-patch HEAD~1..HEAD

or something similar; "HEAD~1" may be replaced by a hash or symbolic reference to any earlier revision. This will produce one or more patch files, numbered and endingth with the extension ".patch". See [[PatchSubmissionGuidelines]] for more on how to get these merged into the public repository.

== See Also ==

* [[CompilingWesnoth]]

[[Category:Development]]

TheRiseOfWesnoth

2013-06-21T00:29:19Z

Anonymissimus: /* Clearwater Port */

== Strategy Guide for The Rise of Wesnoth Campaign ==

===Campaign strategy===

Over the course of this campaign, you will need to level up to some:

* Healers: White Mages/Mages of Light (at least four)
* Undead killers: Paladins (two)
* Mobile strikers: Silver Mages (at least one, preferably more), Grand Knights (several), Fugitives (one or more helps)
* Damage sinks: Royal Guards, Iron Maulers, Highwaymen, Halberdiers, level 3 Burin, and again Grand Knights
* Leaders: level 3 Haldric, level 3 Lady Outlaw, and much later level 3 Commander Aethyr
* Ranged attackers: Great Mages (can use several in the last scenario), Longbowmen/Master Bowmen (two), Trapper/Huntsman (one is helpful)

A Mage of Light, one Paladin, and five Grand Knights make a perfect assault team!

Although Horsemen are key for the first three or four scenarios, it's important not to be too reliant on horse units through the middle part of the campaign, as there are many hard levels underground, in swamps, in water, or against Saurians; use XP from the scenario ''The Vanguard'' to get to 2 Paladins and 2+ Grand Knights.

Don't overlook Pikemen/Halberdiers, which are useful in many levels; pierce attacks work well against Drakes and against the dragon, and they are handy for defensive roles especially repelling Wolf Riders. They are less good against undead, though, and don't get that +1 MP Royal Guard speed bonus.

Due to many undead opponents, you will want to recruit many Thugs at times, and get a few (the quick ones, since you need them underground) leveled up. Footpads help too, once leveled up. Due to swamps, you will sometimes be spamming Poachers, which get marksmanship once at level 3. These, plus Lady Outlaw, give tactical options at other levels too: some decent chaotic troops form an ideal reserve, since you can attack with your lawful troops at dawn, and by nightfall when you need to heal them, use some chaotic troops to either continue the attack or to shield your healing lawful units.

Here are some recommended units to have obtained by specific scenarios:

2. The Fall - 1 Knight 
3. A Harrowing Escape - 1 White Mage, 2 Knights, plus about-to-level troops 
4a. The Midlands - avoid, go to The Swamp of Eden instead 
4b. The Swamp of Eden - level 2 Haldric, level 2 Lady Outlaw, 2 Knights, 2 Shocktroopers 
6. Temple of the Deep - level 3 Haldric, level 3 Burin, 1-2 Mages of Light or several Outlaws / quick Bandits 
8. Clearwater Port - level 3 Lady Outlaw, 3 White Mages / Mages of Light, 3 Iron Maulers / Royal Guards / Halberdiers 
12. A Final Spring - 1-2 Silver Mages 
14. Rough Landing - the 3 loyal Mermen from the previous scenario, ''Peoples in Decline''[glandis] In 1.8.6, there was no opportunity for 3 loyal mermen - maybe this was in an older version? And only Merman fighters can be recruited - no Netcaster upgardes are possible 
17a. The Dragon - up to 4 White Mages / Mages of Light 
17d. Cursed Island - 1 Paladin 
19. The Vanguard - 4 Knights/Lancers/Grand Knights, 2 Paladins (or about-to-level Knights) 
20. Return of the Fleet - 1 Mermen Entangler, 1 Merman Triton with Storm Trident, level 3 Commander Aethyr desirable 
22. The Rise of Wesnoth - 2 Paladins, 3 Royal Guards, 4 Mages of Light

Because the campaign is long and you won't be able to recall all your level 3's in the final scenario, it pays to create some "uber-units". An example is a quick, resilient Silver Mage that has been AMLA advanced a few times.

==Scenarios==
===A Summer Of Storms ===

This is a relatively easy scenario, so gear your recruitment and strategy with an eye towards gathering XP.

Recruitment...
# For the first round, recruit 2-3 Horsemen and the rest can be all Spearmen or a mix of Spearmen and Bowmen as you see fit.
# Then, you should probably hire Bowmen and more Spearmen. Whatever Bowmen you can get advanced will be useful later on for fighting the many trolls, grunts, and riders you will encounter. Note, however, that you will not have any healers until you level up at least one mage to White Mage status, and the sooner you can do that the better. Red mages will also prove very useful in subsequent scenarios, so consider recruiting at least two mages.

Strategy...
* Players have used at least three strategies with success...
# The "over the bridge" strategy: Send the horsemen with the king over the bridge, and the others should follow or start going over the mountain, to avoid being attacked from behind. Send subsequent Spearmen and Bowmen on the "over-the-bridge" road, and when the Prince and final troops have just about caught up, march on the enemy camp.
# The "hide in the swamp" strategy: Proceed much like the above, but send the king with 3 Horsemen to capture the nearest houses, then retreat into the swamp area until you have your lawful bonus to kill off troops during the day. To hold them back, you can use a Spearman and a Mage (to level him.)
# "Sandbagging" strategy: On the hardest difficulty level, the initial enemy assault will only be easy to handle by entrenching your troops behind the river. Use the king to block the bridge initially, while Spearmen handle the shoreline just north and Horsemen carefully flag villages across the river. Run the king around, lending his leadership as you massacre the stupid enemy troops that have jumped like lemmings into the water.
* For all these options, you will also need to send a squad north into the mountains and around into the flank of the enemy. A quick Spearman, a quick Bowman, and one other unit, possibly a quick Mage, should be more than sufficient.
* When you see that the fronts are under control, stop recruiting and send prince Haldric and your Mages over the bridge on a quest for XP, assisted by the leadership of the king, and converge on the enemy camp.

===The Fall===

This is a scenario that looks scary, but it is only moderately difficult with proper recruitment and strategy.

Recruitment...
* Recall or recruit Spearmen and Bowmen to man the lines.
* Horsemen/Knights are desirable, because you probably do not yet have a White Mage, and the villages are widely spaced.
* Recalling or recruiting Mages for XP gathering is highly advisable for future scenarios.

Strategy...
* There are three basic approaches to take out the outlaw leader...
# "Brute force" strategy: You can march west with a large army and use part of it to hold northwestern orc. Use the rest to fight outlaws and kill the leader. This strategy requires a lot of troops but it can bring you plenty of experience and can bring a quick victory.
# "Assassination over the bridge" strategy: You can assassinate the outlaw leader. One way is to wait until the orcs have killed almost all outlaws and then assassinate the outlaw leader with Knights, rushing over the enemy camp's bridge and into the keep. This strategy is risky because orcs can kill the leader before you.
# "Assassination via the mountain pass" strategy: Another way to assassinate the leader is to send a squad through the southern mountains to the outlaw keep. Two Mages and three Spearmen are enough. You may wish to substitute one of the Spearmen with a Knight or Horseman, though horse units have only a narrow passage devoid of mountains and could get pinned by the enemy.
* On the hardest difficulty level, you may be forced to assassinate. For either of the assassination strategies, it is a good idea to fight against the northeastern orc nearby your keep. This way, you can secure your back and earn experience.

Hints...

* Saving the loyal Heavy Infantrymen (or Shock Troopers on easy) pays off in later scenarios. To save all three, move them south towards the outlaws.

* Once you eliminate the HP of the Lady Outlaw, she offers to help you. If you say yes, she comes back as a loyal unit in future scenarios and you will be able to recruit outlaw units, plus she cannot be killed in the next couple of scenarios (instead, she disappears when she goes to zero HP, and comes back the next scenario.) This is quite valuable. If you say no and try to kill her, you find out she cannot be killed. However, you do get 200 gold that she leaves behind.

* Heads up: The following scenario (''A Harrowing Escape'') is a handful on the hardest difficulty level. On hard, a carryover of almost 150 gold (so you have 250 starting gold) would be wise, so although Lady Outlaw's assistance is worth much more than 200 gold, you may be forced to choose the gold. Another thing you need to beat the following scenario on hard is a White Mage at or near the start of the scenario. Also, about-to-level units will be especially nice for their self-healing ability and low initial upkeep. Steer XP accordingly.

===A Harrowing Escape===

This scenario is much easier on lower difficulty levels, calling for different strategies.

On easy/medium...
* Recruitment: You should recruit/recall at least one, possibly two Mages here, and use them for killing Goblin Spearmen and finishing off injured Wolf Riders in the hills & mountains bordering the valley. Other than the Mages, simply recruit what you want, and go along the road. You get enough villages to pay upkeep for quite some army, and can give some of them a bit of experience.
* Strategy: Leave a few units in the rear, as the enemy can cross hills quickly. Note that Footpads and Outlaws will also cross hills at reasonable speed, if you need to hunt down some units. There are two castle tiles about halfway down, try to send Lady Outlaw and Brunin the Lost to them, they make good guards in case the enemy tries to come straight up. You can also send a couple groups of units down southeast to the lake, so you can prevent the Green team (southeast) from coming up the river. You can also kill the two Orcish Grunts (or Warriors on medium) on the southern castle tiles and then move Lady Outlaw and Brunin to them.

On hard...
* Recruitment: To beat this scenario on the hardest difficulty level, you need some level 2 (or better yet, about-to-level level 1) units already and a lot of starting gold. It is possible with ~200 starting gold, but only barely. 250+ is better. You can stretch your gold a bit by not going negative on upkeep and waiting until you can't wait any longer to do one last round of recruiting, recalling mostly level 2's. For timing your final recruitment, watch the wolves that are likely trying to flank through the mountains south of your keep. Another requirement for beating this scenario is a White Mage (or two.) If need be, you must promote a Mage (or two) tout de suite, as you will be dealing with severe damage and assassins, while only having easy access to 2 or 3 villages initially. Horsemen and Knights are useful for dissipating damage by serving as meat shields against blades and then running off to remote villages to heal. Quick Horsemen are especially nice, as they can transfer between two strategically placed villages in one turn, for healing on the go. Horsemen, Knights, and Swordsmen are useful for swatting assassins.

* Strategy: More important than terrain is avoiding getting flanked, so mobility of individual units is key; if you climb up deep into the mountains, you will have a harder time with mobility than staying on or near the valley floor. Additionally, many of your units cannot go on mountain hexes, so it's easier to maintain your lines if everyone stays close to the valley. Near the start of combat, it's crucial to kill units quickly on the road: first the wave of wolves, then the wave of assassins. In contrast to easy and medium, on the hardest difficulty level both pairs of roadside castle tiles are guarded, not just the second pair. As on medium, the guards are Orcish Warriors.

Hints...
* On medium/hard, you can lure out the roadside guard Warriors one at a time by putting a unit within attack range of one (and out of range of the other.) They mostly come at night. Mostly. That is, the Warriors might not bite bait put out during the day.

* If you have Lady Outlaw, note that she has leadership, which will be useful to help promote Prince Haldric, if he is still level 0. It's worth advancing her to level 2, to continue to provide leadership to level 1 Haldric and your other level 1's. You may also make use of her odd ability "distract", which allows adjacent allied units to ignore ZOCs. And Lady Outlaw allows you to recruit outlaw types. On hard especially, Thugs can be useful as meat shields and to provide strong attacks at night when your lawful forces are crippled. Remember too that Lady Outlaw cannot be permanently killed (at least not yet), so when desperate times call for desperate measures, you can move her into a suicidal position.

Spoilers...

* The scenario can be beaten on hard with 154 gold only (I decided to trust the lady). Key points in the strategy I used:
** Underrecruited as heavily as possible, so that the upkeep of my current units was completely offset by my villages. Only 2 footpads to go for Burin and villages down the path right at the start. Only level 2 unit I recalled initially was a white mage. Recalled the 3 loyal HI and tried to arrange it so that they aren't attacked by archers. Recruited several thieves, since they are cheap and the grunts are font of attacking them instead of my mages (and they still often survive on 70% def).
** During the main phase of the battle, stayed on the safe side of the river (this was the actual key point). Used the river, mountains, castle and swamp to have good defense for myself and bad one for the orcs. As shortly as possible before my income turned negative, recruited/recalled an additional 5 units. Needed to give up the village abroad the river as well (so only 3 villages left).
** What also helps as well is the fact that there are two enemy sides as opposed to a twice as strong single enemy side. If one of your units could be attacked by 3 enemies, but 1 of these hexes is currently blocked by the other side, the currently moving enemy decides to attack units which it (they) is (are) actually less likely to kill than that one. AIs don't cooperate, that is.

* There is Dwarf Steelclad in the village at 8,5. It's not far from your camp, so send Lady Outlaw there. Dwarf joins you because "It has been a long time since he felt the satisfying crunch of Orcs under his Axe."

* After you kill the first orc leader, an Orcish Slayer and two Assassins will pop out of nowhere, so you would be wise not to have any wounded units stuck without movement points at that point. Also, the other leader will get an infusion of gold and start recruiting on all available hexes, so if you can sit on some of those hexes first, it will help keep the situation from getting out of control.

* At the end, you will be given the choice of the river/swamp road or the midlands/orc road. These fork to the scenarios ''The Swamp of Esten'' and ''The Midlands'', respectively. The swamp scenario is relatively easy, while ''The Midlands'' could cost you some leveled units or even prove impossible to beat if you are low on gold. Also, the swamp gives you a free loyal White Mage, so it's a no brainer, unless you want more of a challenge.

* Heads up: it would be wise to have at least 1 Mage either levelled up to White or about to level up before going to the scenario ''The Swamp of Esten''.

===Diverging Campaign Path===
====The Midlands====

Orcs again. But you chose that way. This scenario may appear impossible, but with a lot of gold and a little strategy, it can be beat.

Recruitment...
* You are given plenty of time, so use it wisely. The enemies send lots of orcs, mostly weak ones. So recruit and recall everything you can.
* Recall any White Mages you have. You'll need them.
* Bowmen are good for the wolf units you will be facing.
* The rest depends on your strategy.

Strategy...
* The "Fast Assault" option: use an assassination team. If you go west, only your Knights and Horsemen will arrive and fight at daytime. So go south. Take the bridge and defend against the enemy closing in from the west. Take out Yellow with a fast assault team (they should take a healer along), but be careful about the leader. Your main force moves west, takes and holds the second bridge, and takes out Blue. Your assault team stays in the south and goes for the last enemy leader - they won't face any serious resistance. The enemy moves north to support Blue. The HI guarding the bridge might gain a level or die, but hopefully not the latter, as they are loyal units in a long campaign. With this approach, you can finish early (around 25 turns) and keep your losses low.
* The "Dark Assault" option: use Footpads. If you chose to work with the the outlaws in the last round, then this works well. Footpads are cheap. And they are fast. And they have good defensive abilities. Plus they fight well in the dark and in the forest. So recruit lots of Footpads-pawns and quickly dispatch them to the upper west and south, followed by more powerful units: Mages, Horsemen, etc. For the time being, leave the middle enemy alone. To the upper west, send several Footpads into the forest and capture the village and set up a defensive line. This cuts down the enemy's gold and increases yours. Don't attack at first, just defend, until more of your slow higher powered units arrive. The strategy here is to pick off the orcs, and send the Horsemen to capture villages. While this is going, to the south you send your Footpads to capture any villages you can and, more importantly, put a Footpad on the hex that is adjacent to the bridge, thereby stopping easy advancement of their greater numbered troops. A White Mage, a couple Trappers and some Bowmen would make a good escort. Probably sending a Thief or two would be good too, to help dispatch any enemy that infiltrate the villages north of the river. one enemy got into one of the villages on the north of river, and it took a lot to dislodge him. The intention is to engage the enemy so that they are fighting from the river squares, at a huge disadvantage.

====The Swamp Of Esten====

This scenario is not too hard if you are conservative and don't send important units off alone.

Recruitment...
# First round, recall 1-2 quick Knights (or Paladins, if you have them), recruit 1-2 Horsemen, and recall your loyal Shocktroopers or whatever they are now.
# Next round, recruit/recall Mages to kill Scorpions (and Bats) and at least one White Mage to deal with poison, plus maybe a Poacher, as they are good in swamp (and you would like a Huntsman eventually, for its markmanship.)
# A little Thug spam can come next, but you don't need a full third round of recruitment. Then send Prince Haldric off to lend his leadership.

Strategy...
# You must blitz the northeastern leader, or risk getting bogged down on bad terrain facing a swarm of undead spam, which can be nasty at night. Quickly send Knights (or Paladins) and Burin over the ford to start wailing on undead. A disposable Horseman can try to take out Scorpions in this area at first. On the way is your proper Scorpion disposal unit, the Mages and White Mage. Try to kill Dark Adepts with Burin or horse units before they have chance to attack you. As you close in on the leader, hover your mouse over him to watch where he can go, as his ranged attack is nasty and can be followed up by waves of kamikaze Walking Corpses, which can take out a Knight.
# After you have killed the northeastern leader and eliminated troops there, you can either send your whole army back across the ford and south or split your army into two halves, sending one part to each leader. If you have lost several units but have lots of turns left, it's probably safer to stick together. This is not a simple mop-up operation, as powerful undead can take out some of your valuable units if you're not careful. On hard, Shadows are a constant threat at night.

Spoiler...

* Searching the temples is a good idea. Some have gold. There is a free loyal White Mage hiding in (a random) one of the temples - visit the temple close to the keep ASAP, and if not there, try rushing a horse unit or Lady Outlaw to the temple at 19,5. However, some of the temples contain undead, so keep extra troops nearby when you enter one.

===The Oldwood===

This is a relatively easy scenario.

Recruitment...
# First round, recall your (probably leveled up) Heavy Infantry from The Fall and some quick fighters.
# Second round, recall White Mages and quick Mages.
# Third round, round out with Thugs, Bowmen, and Spearmen, preferably quick.

Strategy...
* Your forces will have three main combat arenas: the northeast, the south, and the middle.
# The main bulk of your force, including at least one White Mage, should head east to the orc in the northeastern castle. The leader there recruits a lot of units, and most of them are level 2, so watch out.
# Haldric, a White Mage, your loyal Heavy Infantry types, and a couple of level 1's (maybe a Mage and a Thug) should head south to the other orc leader. A few effective melee units can easily counter the riders they send early on, and then with a little forethought and patience you can take out their Archers and Crossbowmen without giving them time to shoot.
# The castle in the middle is inhabited by the tree folk, so don't bother sending troops there; however, you might want to keep a couple speedy units not far off to watch their backs, in case the allied leader gets into trouble, as is usually the case.

Spoilers...
* The temple contains the entrance to the catacombs, but you need the leader Wose's help to open it, and to get that help you have to win the current scenario, so there is no point in visiting this temple.

* Heads up: The next scenario is in the catacombs, i.e., underground, and it's a tough one, so you need to groom your roster accordingly. Two Mages of Light would make it a whole lot easier. Failing that, level up your fearless loyal Shocktrooper and chaotic outlaw types. Bandits/Highwaymen and Fugitives are especially nice. Quick units of almost any type (except horse units) will be helpful, if leveled and possessing high HP (>50).

===Temple in the Deep===

You will be facing undead underground. This is a difficult situation that will prove much easier with proper recruitment. Then the strategy will be fairly straightforward.

Recruitment...

* All in all, what you need is a small elite force. Two rounds of recalls is enough, if you didn't lose Burin in a prior scenario.
# First round, recall your loyal Shocktroopers / Iron Maulers, especially the fearless one, though their slow movement will prove frustrating. Also on the first round, recall a fast "tank" and someone to grab the holy water (if Burin is not your choice.)
# Second round, recall any Mages of Light you might already have, and a total of at least two White Mages or Mages of Light, preferably quick. For the rest of your recruitment, what you need are high movement (6+ MP) non-horse units with high hitpoints (>50 HP), preferably chaotic, preferably with a ranged attack, and preferably impact attacks. Put all the requirements together and it points to Fugitives. Outlaws and quick Arch Mages are worth recalling too. Fill out the rest with Bandits/Highwaymen, Trappers/Huntsmen, and Longbowmen/Master Bowmen, preferably quick. You might think that Red Mages would be good, but they attract melee attacks that they likely will not survive. Note that Horse units are too sluggish to be useful here and should not be recalled/recruited.
# Third round (optional), you can add a unit or two for a safety margin.

Strategy...

# There are two ways north, but they will meet up together before you meet any enemies besides the Tentacles. Ignore the tentacles for the most part and only kill them when it's convenient, as you will need to have a strong line set up by the time you engage the undead. Watch out for the enemy's Bone Shooters, Revenants and Deathblades, as they could easily mess up a level 3 unit. Once you see the two choke points, hold them so one of their units is facing 2 of yours (preferably with a White Mage behind them). You may be able to level up a White Mage to a Mage of Light while fighting in the choke point. If your troops are too slow to grab both choke points, you can send Burin and others to the west choke point while your slow troops line up at the southeast shoreline and bridge.
# Gradually progress northwards once the flow of baddies has tapered off, and once you get into the final chamber, the boss should be a piece of cake, although his ranged attack is devastating, so try to attack him with melee units. Be careful if he has recruits around, as their combined damage can take down one of your level 3's. Note that the Ruby can only be picked up by Haldric.

Hints...

* Holy water: Burin is very effective if you give him the holy water; however, it's more helpful to send Burin running to the west choke point without delay. A good alternative is a Highwayman - or a Bandit, who should level quickly. Compared to a Highwayman/Bandit, Prince Haldric or a Royal Guard is not that great a choice for the holy water due to their lawful alignment and -25% penalty, unless you have (or will soon get) a Mage of Light.

* XP: Use this level to get experience. The early-finish bonus is tiny. The tentacles are perfect for leveling up units. If you're hurting for leveled chaotic units, you can even level up two raw recruit Thugs (use Haldric's leadership to assist). Keep Burin away from the water at this stage, or he'll kill all tentacles as they attack, depriving those who could benefit from the XP.

Spoilers...

* Your killed units will be turned into Walking Corpses (or Soulless on hard.) Therefore, spam is not helpful. A Mage or two can be okay, if used with great care, but mostly you need to recall leveled troops here.

===Return to Oldwood===

Plot only.

===Clearwater Port===

This scenario is easy if you take the first boat out, more and more challenging for the second and third boats, and very difficult (on hard) if you want to take out all three leaders.

Recruitment...
# First turn, recall your loyal Shocktroopers / Iron Maulers from ''The Fall.'' You will also want several Footpads, for speedy village snatching, coastline defending (under leader supervision), and possibly for filling castle hexes if your lines get too thin.
# Second turn, recruit/recall more low maintenance units. It's a good scenario for leveling troops, so recalling acouple half-leveled Spearmen or similar is a good idea.
# Third and later turns, start recalling your high maintenance units. The key to winning this scenario is to recall several advanced units that can take a lot of damage and get good defense in castles (no Horsemen). You will also want at least 3 White Mages or Mages of Light.

Strategy...
# Backstab your ally, stealing all his villages. Your ally is useless anyway, except for the entertainment value from his troops' suicide runs. The income is much better in your hands.
# Send your heavy duty troops with some White Mages over to the line of castle near Lt. Aethyr. (Optionally, you can rush forward past the castle, but you will need to return almost as quickly before the main enemy wave and night arrive.) Aethyr will usually be done recruiting by the second or third turn, before the enemy reaches you, so fill the entire line with your units, and put Knight Sir Rudry in the one non castled tile (or leave it empty, if no enemy are adjacent.) Place the White Mages behind this line. After the enemy has reached you and it is your turn to attack, go mostly for the assasins, as they have a weak melee attack and their poison can be a huge problem. Alternatively to using the castle (from (26,18) to (24,15)) to defend, the front line can lead through the villages at (30,17) and (30,18). This will make your line much shorter, it becomes much more of a bottleneck fight and offsets your enemy's superior numbers, since some of their units just move around with all spots to attack occupied; you only have to give up 1 village and 2 front units instaheal without mages. Place your strongest units on the weakest spot (29,20) and a Mage of Light on (30,19), he will hardly be attacked as the hex before him is used to attack (29,20). This shorter line requires less units on your side and also has the great advantage that there are much less 40% defense spots to attack you. They will flank you at the sides but stand on ice or sand then.
# Meanwhile, on the northeastern coast, the northern enemy leader will send lots of units to catch your flank unguarded. Send 2 Footpads, a Spearman, Lady Jessene, and Haldric to guard the coast. If Lady Jessene is already level 3, you can substitute a Royal Guard, Swordsman, or Javelineer for Haldric. This coastline defense squad may need help later, so be ready to divert a speedy powerful unit there. If you keep a healthy unit on the village at the tip of the land, then, unless you are very unlucky, you will be able to hold off everything the northern leader sends. After the assault from the water has been crushed, some of your troops may be able to cross the ford north, but be careful not to get attacked in the water with only 20% defense. (Certain of your chaotic units do have 40% defense in water; now is a good time to pay attention to that.) Also, notice that the lighthouse has a similar effect as a Mage of Light.
# You have two options for the endgame:
## "Total victory" strategy: Once you've thinned the enemy to where they only have a few units that are close to your line, usually this happens conveniently around dawn, move your people out and start heading for their leaders. Split your force, sending a few down the southern path, to distract the eney and most of them toward the middle leader, to kill him. Once he's dead, send some of your army down to kill the southern leader and devote a few units to defending the bridge until the rest of your army can rejoin you. A unit or two with a lot of HP with a white mage are usually enough to do this.
## "Run like hell" strategy: Alternatively, you can leave your leader near the docks and take one of the boats to end the scenario.

===Fallen Lich Point===

This is a high variance scenario. It may be very easy or very hard, depending on events beyond your control.

Recruitment...
* Recruit fairly lightly initially, as you will likely have a chance to use the Lich's keep to recruit again.
* Mages, White Mages, and Mages of Light are good, and as are all the other advancements of Mages.
* You automatically should have your loyal Knight. Because of the mountains around "lichland" and frozen ground everywhere else, additional horse units are not recommended, except a single Paladin will come in handy.
* Some Thugs or a Bandit or Highwayman will provide a little extra undead bashing power.
* Footpads will help with village flagging, after the Wolf Rider types are taken care of, but you can postpone buying Footpads until after killing the Lich.

Strategy...
# The Orcs will be busy with the Yetis, so you can walk with a big group south and kill the Lich-Lord. Move Haldric to the stone monument to de-petrify the Lich. It may help to post some units around the undead before doing so. Use several mages to make a hole or two in the ring of undead, and then push in a burly fighter or two and/or Paladin to kill the Lich.
# After killing the Lich, assess the Orc/Yeti situation (as well as the empty village situation) and decide if you need to use the Lich's keep to recruit some reinforcements.
# After that, head north and walk into the sewer entrance (the "cave") or else kill the orc leaders.

Hints...
* It is also possible, if you recruit heavily, to split your force and head north to attack the eastern Orcs before they finish with the Yetis. However, be careful not to be attacked by a Yeti yourself; a Yeti is dangerous even if heavily wounded. A Yeti will attack you if it can get to a unit within one turn (and it doesn't have a more appealing orc target.)
* When dealing with the Lich, be aware that he has money; if you let him vacate any of his encampment tiles, or if you kill any of his units but do not occupy their tiles, he will be able to recruit. (This is not necessarily all bad, as it can mean more experience, but depending on the strength of your force you may want to be careful.)
* Note that this level becomes a lot tougher if the Yetis get poisoned early on and quickly die. If this happens you basically have no other choice than to kill the orc leaders first.

===Sewer of Southbay===

This is a swampy underground scenario, but with attention to recruitment, it's not very difficult.

Recruitment...
* As always underground, you want non-horse units with 6+ MP.
* Recall White Mages / Mages of Light, at least two, three is probably the optimal number.
* There are quite a few villages in this cave, so an expensive force is supportable, though not necessary. Some players recruit a large and spammy force, while others go with small and elite:
** Option 1, "Large and spammy" recruitment: Recruit four each of Mages, Thugs, and Poachers. Yes, Poachers normally stink, but here they really shine in a swamp that is permanently dark, underground. If you recruit four Poachers, you could finish with three Trappers and a Huntsman - or you could finish with four dead Poachers. The Thugs are especially likely to die, as they will be facing off against Red Mages, but somebody has to do it.
** Option 2, "Small and elite" recruitment: Recall something like one Red Mage, one Arch Mage, one Silver Mage, 2 twooyal Guards/Highwaymen/etc, and a Trapper or Huntsman, plus three regular Mages and a Poacher.

Strategy...
# After leaving your initial chamber, you will be in a large swamp room with three entrances, through which will be a flood of bad guys. Use two Poachers and a Thug or similar to blockade the southeast, a small elite group to block the north, and then a mix of fighters and mages to handle the west entrance. Give each group a White Mage or Mage of Light, as well as at least one regular Mage. Try to keep the Mages of Light away from your chaotic forces on the front lines, though. Use the leadership of Haldric and Lady Jessene - and Mage of Light illumination or lack thereof - to get the most from each attack.
# When the initial battle has died down, you have two options:
## If you have enough forces, you can divide into two groups and attack both brothers simultanously, east and west.
## Otherwise, do them one after the other, and then look for the exit.

Spoilers...
* Danger: there is a Giant Spider at the exit. You may wish to keep one or two cannon fodder units in order to be able to save your advanced units. It is best to use ranged attacks against the spider, so leveled mages are good here.
* Heads up: the next scenario is a lot easier with a lot of gold, especially on the hardest difficulty level.

===Southbay in Winter===

Plot only.

===A Final Spring===

This is a large battle, and any mistake on any front can spell doom, but overall it will be fairly easy on the easier difficulty levels. On hard, it will only be a cakewalk with a lot of starting gold (more than 450 or so.)

Recruitment...
# On the first turn, recall a Silver Mage to teleport to the island, recruit Footpads for village snatching, recall one or more of your loyal Iron Maulers (leveled up Heavy Infantrymen from ''The Fall''), and recall one or more Knights or similar.
# Second turn, continue with this theme, but it will be nightfall soon, so recall Outlaws, Bandits, Assassins, etc.
# Turn three is a bit more of the same, but you need to start thinking about preserving your income and also keeping a gold reserve. You can spam some peasants to preserve cash and income.
# Turn four turn is more of the same.
# Turn five is similar, but it will be day soon, so lawfuls like Knights and level 1 Mages are a good idea.
# Turn six, you will have new recruitment options (see spoiler at walkthrough end.)

Strategy is broken into four fronts...
# The first front is the south land area. Do a counter-clockwise sweep with mounted units, optionally augmented with Footpads, which can help pad out your lines with forest and village hexes. Note that it will be nightfall soon after game start, so it might be wise to delay any serious mounted assault until the next day, and you can delay your recalls for this.
# The second front is the walled city. Move slower units and your loyal White Mage / Mage of Light to defend here. Take your ally's villages; your ally wouldn't do much useful with the money anyway. When your mounted units from the second front complete their sweep, you can break the remaining southern forces against the city wall in a hammer and anvil. Then your united forces can move north. On easy, you may be able to push north more quickly than that using just part of your city troops.
# The third front is the bay and peninsula north of your keep. If you don't protect this area well, Wolf Riders and others will mount an amphibious assault in an effort to flank your troops. On the easier difficulty levels, you may wish to beat the punch and quickly establish a bridgehead on the other side of the bay.
# The fourth front is the two small islands. Send a Silver Mage there ASAP. (You should have a village already there, so the Silver Mage can teleport over.) Footpads/Outlaws/Fugitives and others will help later. Lady Jessene could be used. A quick White Mage would be useful, either on the coast or on the islands. Do not use Assassins on this front. Assassins have relatively weak defense in water against Orcs and Nagas, they're very weak against blade, which is all orcs and nagas use, and their relatively slow movement in water makes backstab hard to use reliably. Overall, you need to devote more resources to this front than you might think.

Hints...
* You should have lots of high-level units now, so concentrate on recruiting new ones and levelling them up to fill needs.
* Peasants are useful as placeholders for villages and distractions for the enemy.

Spoilers...
* On turn 5, a gang of nasty undead show up in the east. So, for your city taskforce, you'll want to recruit/recall units with impact and arcane attacks. Note that if undead capture villages, they will be flagged with the Orc island boss' black flag! This can result in an overwhelming number of Nagas, and it's one reason that you must devote a lot of resources to the island campaign. Flag any black flag villages you can.
* On turn 6, a gang of nasty Mermen show up in the west. Fortunately, they are on your side. You can now recruit Mermen. This is the real reason to keep a gold reserve until this time.

===Peoples in Decline===

This is a bloody scenario versus Drakes. It can be a real challenge on the hardest difficulty setting, less so on the easier levels. Proper recruitment is more important than strategy here, as you will have little opportunity to maneuver.

Recruitment...
* Drakes can be dangerous, so this is a great scenario to use the time honored technique of cannon fodder. Now that you can recruit level 0 units for cheap, you can protect your higher level units by recruiting endless Peasants to distract the Drakes' firepower.
* Drakes are vulnerable to pierce attacks, so spam cheap pierce attack units. In addition to Peasants, there are Poachers, Bowmen, Peasants, Spearmen, Merman Fighters, and Merman Hunters. Poachers are key here, due to the swampy terrain and their chaotic alignment.
* You will need about 3 White Mages / Mages of Light in all.
* On your last turn of recruitment when you have about 80 gold, recall some advanced units, like Master Bowmen.

Strategy...
* Since you will have a lot of level 1 and 0 units, make sure to use the leadership of Prince Haldric and Lady Jessene.
* Look for opportunities to heal via leveling up.
* Pay attention to the day-night cycle in this scenario. Drakes will be strong during day, but become very weak in the night.
* Take advantage of the mountains for defense, but note that on hard, you need to set up a relatively small perimeter around your base, as you will be hard pressed to even hold a small area.
* Be careful with your loyals.
* Because most Drakes have powerful ranged attacks, the roles of your melee and ranged units are reversed from the norm. Whereas usually you would use fighters to protect archers, here you will use archers to protect fighters. Melee-only units should hide behind the lines until they attack, preferably at night (with a Mage of Light supplying illumination.)

Spoiler...
* Make sure you get the Storm Trident in the middle of the sea, but be certain that you've cleared most of the Drakes first, since a Sea Serpent will appear. It's best to have some strong units ready to kill it in 1 or 2 turns. You can give the trident to Lord Typhon, but since he leaves a bit later, you may want to give it to another Merman Fighter. Movement over land is important for Mermen in the campaign as a whole. If the Merman Fighter to whom you give the storm trident has the Quick attribute, you can make him a Hoplite when he gets to level 3. Otherwise, make him a Triton, because movement over land is important for Mermen in this campaign as a whole.

===Rough Landing===

You will be fighting Nagas and Vampire Bats, primarily. This is a scenario that may be frustrating on the easier difficulty levels, though on hard it is just par for the course. Good recruitment and strategy will save you from getting slaughtered.

Recruitment...
* You are probably going to go negative on gold and be unable to rectify that with the paultry early finish bonus, so you might as will go very negative and be resigned to start the next scenario with minimum gold.
* Recruit/recall many Mermen and 1 or 2 White Mages or Mages of Light. A few Peasants can be useful to pad out your force, distract the enemy, and protect villages from stray Bats. A Silver Mage can be useful for island hopping but is not essential. Thieves/Assassins are blade vulnerable, and Nagas only use blades, so it's probably best not to recall them.

Strategy...
# Knock out the southeastern leader in a blitz. It's important to get that out of the way, because a wave of Nagas is advancing at light speed from the north.
# Next, hurriedly set up a line in the water alongside your fortress island. Your fortress troops can anchor one flank, while Burin the Dwarf can go to the island to the northeast to anchor the other end of your line. Nobody messes with Burin. Move Lady Jessene behind the lines to lend her support to the Mermen. Your loyal Mage of Light will be able to move back and forth more (to lend illumination) if kept in the fortress area.
# Finally, once the enemy assault wave has been broken, advance northward to kill the final two leaders in a straightforward mop-up operation. Just be careful not leave isolated units where they can get swarmed.

Hints/Spoilers...
* Try to level up the mermen; they can be useful in another scenario later.
* Beware of Sea Serpents. Three of them will appear, one on each of the three turns following your first kill of an enemy unit. Make sure to kill them at once. The Storm Trident from the previous scenario and the Ruby of Fire will come in handy against the Serpents.

===A New Land===

This is a non-scenario. The scenario objectives tell you to avoid all confrontation for as long as possible, but actually the faster your units encounter the others the faster the scenario will end.

Recruitment...
* None necessary.

Strategy...
* The optimal strategy for gold carryover is to grab the three closest villages, then retreat to your keep and wait. Once one attack occurs, the non-scenario will be over.

Spoiler...
* One thing to keep in mind is that this the last chance you have to grab some more Mermen as their king leaves. They are quite helpful in a later scenario so grabbing a few extra here cannot hurt if you can spare the gold.

===The Ka'lian===

Story, with your choice of four battles next. You have to beat them all in whatever order. The amount of gold you have should be the factor in deciding when you choose to play Cursed Isle (the undead problem).

===Diverging Campaign Path===

All four scenarios have to be beaten, but in whatever order you choose.
====The Dragon====

This scenario is not as difficult as it looks, though your recruitment and strategy need to be tailored to fight the Saurian Skirmishers and other foes you will face here.

Recruitment...
* Saurians use piercing attacks mostly, so it's better to use units resistant to pierce. Pikemen and Halberdiers have 40% pierce resistance. Javelineers are ideal as Saurians use ranged attacks a lot.
* You may wish to bench some or all of your loyal Iron Maulers. They are ineffective against the 70% impact resistant Mudcrawlers, while also vulnerable to the ranged attacks of both Mudcrawlers and Saurians.
* Consider adopting a force of all units with ranged attacks, save for horse and thief units, which can be kept behind the lines when not in use. It is amusing when Saurian Augers are forced to tap your units with their little staffs.
* Healers are a necessity to deal with the heavy damage your units will be sustaining. Depending on the strategy you adopt, you will want 2-4 healers. Mages of Light rock here, as they can easily do front line duty in pairs and their illumination blinds the Saurians, reducing their damage.
* You need something to clean up mud. Versus level 0 Mudcrawlers, Horsemen and their advancements can charge with no counterattack, and likewise Thieves and their advancements can backstab with no counterattack. Mages can be used as well on the fire vulnerable mud.
* A Merman or two will help with water hexes. An Entangler's slow ability will help tame the dragon.

Strategy...
* Players have used many different strategies with success:
** "Hedgehog" strategy: Fighting Saurians requires a disciplined formation. If you're used to stringing out troops to move them into position as they get there, that won't work after Turn 2 or 3. You can use a "healing hedgehog" of ten troops--two white mages next to each other and eight troops completely encircling them. If someone gets badly injured, move them to the inside and put a white mage on one of the long edges, fighting as you go. If you're trying for the big bonus, you'll need two hedgehogs. Try to keep reserves back a bit in cities. If the terrain favorably protects you, or the wounded is a fast unit, you can try moving wounded back to cities too. Once the main wave of Saurians is broken, you can string non-wounded troops out a bit in the rush for the leaders.
** "Triangular Hedgehog" strategy: Switching wounded units to the inside of the hedgehog can be a problem if you are surrounded. ZOC prevents you from creating an open hex to move the inner unit into. You can fix this by creating a triangle with three hexes inside, instead of the standard two of the hedgehog. If you do this on your castle, only three units are in grasslands. If you set it right, you can make most of the hexes adjacent to your triangle be grassland as well, forcing the Saurians into a bad defensive position. In terms of unit positioning, the simplest way is to fill two inner spaces with Mages of Light, a but a better tactic is to put one of the mages on an edge, thereby ensuring that all but one of your units are healing. The remaining unit can either be a Merman Hoplite, (prefereably resilient and carrying a Storm Trident) or Lady Jessene, since she has excellent defense and is chaotic and therefore benefits by not being in the Mages' light.
** "Giant Hedgehog" strategy: Recruit a lot of units, and then move the whole army as one big bulk. Keep healers in the middle (about four), rotate stronger units outwards, and make sure you leave no gaps. The Saurians will slip through the tiniest gap and kill your weak units. Head first for the east or wast leader, but steer for good terrain, because your force will soon be swarmed until about turn 10, when there should be many few Saurians alive.
** "Standard Line" strategy: Form a line from the west board edge diagonally up towards your keep across the two villages just in front of the forest. You will probably wish to bend upwards at the forest, rather than running the line all the way to the keep. Whenever the Saurians have a small number of troops at your line and you have enough strength to kill them all, you can advance your whole line one hex south, allowing you to get additional attacks on them from non-frontline troops. Once you advance a unit to the first water hex at west board edge, the west leader will probably come out to greet it, so be ready to fry him with Haldric's ruby. After killing the leader, back up into good terrain to prepare to meet the dragon.
** "Wake the Dragon" strategy: Prematurely wake the dragon (see spoiler below) and back up your troops to north of your keep. When the dragon comes, kill him. The scenario can be over on turn 7. There is no early finish bonus for this, but you can recruit lightly so that you still have gold at the end and will carry-over 40%, if you need it for your next scenario.
* With all these strategies, the Saurians may hold back for quite a while. This is okay, as the Dragon will eventually appear and come to you. Kill it. Then you are given a choice of whether to end the scenario or to try to kill all the enemy leaders before time runs out. You can choose to finish the remaining Saurians for a nice bonus. However, on the hardest difficulty setting the turn limit (33 turns) is insufficient for you to plow through the vast hordes of level 0 spam to get to the leaders, so it's best to simply end the scenario after killing the dragon.

Spoilers...
* The dragon will awake on turn 15 or when you move a unit down around the road north of the mountains. If you wish to wake the dragon prematurely, you can recruit a Horseman on turn 1 and run him down. It's a suicide mission for him, however.
* If you have a fast non-horse unit in position, rush it to the mountain cave after the Dragon leaves to grab the 200 in gold, though that's nothing compared to the Hero bonus for defeating all the Saurian leaders. So focus on killing all of them first.

====Lizard Beach====

This is a scenario versus Saurians, Giant Scorpions, and Mudcrawlers, where good recruiting and strategy will save you from massive bloodshed.

Recruiting...
* Mermen are helpful for the swamp and water areas.
* Bench some or all of your loyal Iron Maulers, veterans from ''The Fall.'' They are laughably ineffective against the impact resistant Mudcrawlers - and laughably vulnerable to their ranged attacks.
* Thieves, Horsemen, and their advancements are good for mud cleanup, though you must keep them out of range of Saurian skirmishers. Swordsmen and Royal Guards are also good, though overkill.
* Recall a lot of fairly high HP units, preferably with strong non-impact ranged and melee attacks.
* Mages are good. Mages of Light are especially useful, since they can do front line duty. Lots of healing may be necessary, about 3 healers are good, so White Mages can be used too. Raw recruit Mages can be used as well, for disposal of Giant Scorpions and the occasional Saurian Skirmisher that wanders too far. At least one Silver Mage is highly desirable, along with a speedy unit (e.g., Fugitive, Footpad, or Horseman) to capture villages for the Silver Mage to use north of the river.
* [fredbobsmith2] An alternative strategy that works surprisingly well is to simply use a very mage-heavy army. Recall most or all of your high-level mages, throw in a few peasants, and spend the rest of your gold on recruiting mages. Victory will come with shocking ease.

Strategy...
* General strategy: as Saurians have skirmishers and a lot of movement, be sure to protect your wounded units well. Because of the Saurians unnerving ability to concentrate their fire on one unit, be sure to keep several healers around and try to keep your line straight so only two can mob one guy. Hedgehog tactic also seems to work well.
* Opening strategy: here are some specific strategies that players have used with success in the early part of the scenario:
# "Mermen in center" strategy: Recall 2-4 Mermen, 1-2 Trappers/Huntsmen, and a lot of high HP troops, then form a line. Initially, you can either form a north-south line around the lake area with one flank at the south board edge, or, if you want to be conservative, you can do a diagonal line in the southeast corner, with both flanks tied to board edges. You'll need the Mermen to handle the lake area, and Trappers/Huntsmen/Mermen for the swamp areas. Keep troops in reserve, so that when a few Saurians meet your line, you can advance your whole line over them. Do not be too conservative/defensive on hard, as your time is limited.
# "Mermen on flank" strategy: Recall several decent land melee units & then 4-5 level 2 Mermen on rounds 2-3. Most of your force forms a line of battle near your keep, Mermen on the north flank in the river, land units extending south, flanks bent back with strongest units at the corners - then let the Saurians break on it. Once their first wave has broken, the rest of their troops come in drips and are no problem, so now you can split up and wipe out the stragglers and claim villages; any L2 units you start with should level up. After you defeat the main force from the south send just one or two guys north to capture towns so your Silver Mages can teleport into the fray.
# "Mermen feint" strategy: Recall most of your Mermen from before and send them along the river towards the sea. This will harry the saurian troops coming down from the north, allowing your main force to advance on the southern enemy undisturbed. Beware, though as your mermen will encounter the Saurians at night time (giving you -25% and them +25%), so try to minimize conflict until dawn, just get in their way.
# "No Mermen" strategy: On your first two turns recall two keeps of strong, fast veterans like mounted units (not Paladins though; they're pretty ineffective against saurians), Outlaws/Assassins, and Silver Magi along with some other veterans, preferably with a lot of HP: if all goes well (at least on easy and medium) that may be all you need. Dash them across the swamp directly west of your keep, south of the sands, and form a line with strong units at the ends. They'll flank you, but you're stronger than them and you can use your slower units to crush the flanking saurians in a hammer and anvil. The first wave of southern Saurians should get itself killed before the northern Saurians arrive in force. Once the northern Saurians arrive, take them out with your slower units while your quicker ones go for the southern leader.
# "Sacrificial lamb" strategy: In addition to a couple mages, 2 healers, and some other fighters, recruit a castle-full of peasants to draw the Saurians out onto open ground. Surround a single peasant on 5 sides, with 2 healers behind him. Build your formation around that.
* Closing strategy: The enemy's onslaught tapers out after their initial wave, so the final push for the southern leader should be quick and clean. Taking out the northern leader is harder, because all of your units will be stuck south of the marshes and the river. If you want to go for a quick win, just march forth with Silver Mages, Mermen, and anyone who's close enough to be a help. If you don't want to lose any of your better units, patience may be the key.

Spoilers...
* When one of your units gets as far west as the second bridge, a wave of Nagas will arrive out at sea. You may wish to delay going that far until the second watch, so that the Nagas will make contact with your forces during the day.
* Killing one leader gives more gold to the other, so when you've defeated pretty much all the southern leader's forces, just plant a level 3 or two in his keep and leave him alive; kill them both in the same turn.

====The Troll Hole====

This is a scenario that you cannot win by brute force, because the trolls have more brute force than you. Wise recruitment and strategy are necessary.

Recruitment...
* It's underground time again, so as before, mainly recruit mages. The trolls are strong, so hopefully you have lots of levelled up mages. Mages of Light are especially nice, because they are tough enough to survive an attack from most trolls, while simultaneously reducing the damage sustained (due to illumination blinding the trolls.) Level 1 Mages can be used to good effect too, especially if quick. If only attacked by a single Troll Whelp, a healthy level 1 Mage will survive.
* In addition to mages, your chaotic units can be helpful here again, especially against the occasional Rocklobber, which you will not want to attack with mages.
* Forget about your loyal Iron Maulers (leveled up Heavy Infantrymen from ''the Fall''). They are too slow. It's not that you'll be running around, but you will be rotating troops due to heavy damage, and they will only get in the way.
* Putting Mermen in the moat will really help you fend off the first wave of attacks.

Strategy...
* There are 4 castles, and two of them (randomly placed it seems) are the troll leaders you need to kill.
* Try to use the narrow corridors to your advantage, so the enemy can only place one attack against a strong unit of yours, but you can kill a troll at a time with two mages or Haldric. Also keep an eye at your back since they will try to surround you. And resist the temptation to send single units wandering around in what seems empty caves - they will all die, probably by the fangs of a Giant Spider.
* Try to arrange it so one troll can enter to be attacked by many troops. Have regular troops in front initially. Move mages forward to finish the troll, plug the gap where the troll was with Burin or a Royal Guard or an Iron Mauler, and reset the trap on the next turn. When you've whittled down the enemy, go the direction they came from and kill the leaders, ignoring spider keeps.
* Alternative: This could be a good choice if you have low gold: recall 2 quick red mages, and 3 quick tough melee units (say 2 royal guards & a L3 chaotic unit like a Fugitive). Play expedition style: abandon the start island, stay fairly close together, with your troops roughly divided in two between those moving forward and those fighting rearguard. Provided you knock out one troll leader early, the rest is manageable, just work your way carefully over to the other.

====Cursed Isle====

You will be fighting undead, mostly of the incorporeal and ghoulish lineages. Victory comes surprisingly easily.

Recruitment...
* Recruit lightly, certainly no more than two castles of troops. You could use 1-3 Paladins, 1-2 Mages, and 1-2 White Mages / Mages of Light.
* Recall your loyal Merman Triton or similar and have him pick up the holy water.

Strategy...
* This can be the first or last quest you choose. If you can wait, do it last, as you will come out of it with a lot of gold, which you will need for the first scenario after the quests, ''The Vanguard''.
* Keep a very tight formation for the first night, as Shadows will hit hard and you don't want to get backstabbed or swarmed. By dawn, it should be smooth sailing.
* If you get anywhere near the enemy leaders' keeps, expect to get rushed by a leader.

Spoiler...
* In one of the three temples there is a Vampire Lady. All you really need is a Paladin or three to rush the temples. Kill her. Game over, you win. One of the other temples has some gold; grab that first.

===A Spy In The Woods===

Plot only.

===The Vanguard===

You will be fighting a large number of orcs, trolls and other enemies in a location with a natural defensive line, where presumably an underground river has carved a line of sinkholes. This scenario will be difficult or impossible with minimum gold (200), but quite doable with a large amount of gold (450+) even on the hardest difficulty setting. Recruitment and strategy are fairly straightforward, given the board layout.

Recruitment...
* Recruit a lot of units; you will need them.
# First turn, recall/recruit speedy units: Knights, Lancers, Paladins, Horsemen, Outlaws, and similar.
# Second turn, recall your loyal Iron Maulers (leveled up from ''The Fall'') and Spearmen/Swordsmen/Royal Guards.
# On subsequent turns, recall/recruit healers and other sorts of Mages, Thugs and their advancements, and Longbowmen. You will need quite a lot of healing power: 3-4 White Mages / Mages of Light and 1-2 Paladins. A Silver Mage would come in handy, since your forces will be widely spaced, but you could start with a couple of Red Mages and try to level up one or both to Silver Mage.

Strategy...
# This map is smaller than fog of war and sinkholes make it appear. Rush the west and northwest gaps with mounted units, but slow & strong will carry the day once the sun rises and the odds are in your favor.
# Seal of all the gaps in the ring of sinkholes. When the onslaught begins, wounded units can retreat back into villages or be cared for by healers - or actually both, since soon you will be out of non-wounded units.
# A "Sitzkrieg" may develop, where neither side can make progress. Shift units to the southwest and break out there, using the west board edge defensively. From there, sweep northwards, taking out the western orc leader first and then the next orc leader.
# Don't forget the chest of gold, which you can see even in fog.
# End the scenario with the kill of the final leader, a level 3 troll.

Spoilers...
* Once you kill more than half the units of any side, a few tough undead units will appear near that side's stronghold at the edge of the map. So, this will happen three times. Beware the Chocobones. Their double damage from charge means they can take out Commander Aethyr at night just by hitting 2 for 2, and they will certainly try if they get the opportunity.
* Heads up: the next scenario is much less difficult with extra gold. You can use Peasants to avoid going negative on gold, promoting them to Spearmen only when needed.

===Return of the Fleet===

Welcome to the "kitchen sink" defense. You've made it this far; now the enemy will launch a desperate defense, throwing a little bit of everything at you. The effect is mostly psychological, but it could be a problem if you came into the scenario with minimum gold or your initial assessment causes you to drastically under-recruit. Time is money.

Recruitment...
* On medium, at least, you don't want to overrecruit. First turn, recall Mermen to assassinate the undead leader; 2 Entanglers/Netcasters and the Triton with the Storm Trident. Later, you should recruit 1 or more Silver Mages also for this taskforce as well as for causing general mayhem. It's also worth recruiting 5-10 L1/L0 units to take the brunt of the first wave of attacks; you can use any combination of Footpads, Poachers, Thugs, Spearmen, and Peasants, as you see fit. You'll want some decent L2 and L3 recalls for healing, to flank your lines, and to start kicking some butt at daybreak. A Mage or Red Mage to blast Trolls and Chocobones will level up by end of scenario. Paladins are good too. In addition to your loyal Mage of Light, you will need a bare minimum of 1 more healer.
* On medium, don't recruit too much for fighting the undead - 2 Paladins at most, 1 or 2 Thugs, the stormy Merman, and the nearest Mage working with your land force are sufficient - the undead commander only gets 5-6 L2 recruits and they come ashore scattered (on medium, anyway). Paladins are so effective against undead that you can wade into the water after them. Just remember, Paladins can't go into deep water and undead can.
* On hard, you also don't want to recruit too much for fighting the undead, but it's only because going on an offensive early against them will get you crushed by a Chocobone armada.

Strategy...
# Move the Mermen (including the storm trident) as quickly as possible pretty much straight to the West. (There is a village and swamp hex that can aid your travel if you pick the best route). Move these guys up the West side once they get there to get to the Undead Leader as quickly as possible.
# Your loyal units can do a little village grabbing, but it would be unwise to venture too far north.
# After nightfall, fog will appear; for the rest of the scenario, the map will become shrouded, like in a cave scenario. So while you're still amazingly able to see, note the key terrain features, castle and city locations, and troop dispositions (especially Chocobones.) Also, visually explore the avenues of approach you want to be able to see later.
# The first wave is largely at night and will have Goblin Knights and Pillagers, and later Chocobones and Troll Warriors. The damage they can cause is bone chilling, so make sure to divert their attention with plenty of spam. You want to meet them on the edge of the woodland, while inducing the orcs to fight from the grassland. Footpads and Poachers are handy here, as they have high defense in woodland. Players have had success setting up the initial line in either the north and northeast woodlands, with respect to the castle. Others have succeeded by fighting mostly from the open plain, retaining mobility by leaving the woodlands to their Footpads.
# Once your Mermen have taken an island city, teleport over one or more Silver Mages to help kill the undead leader - in addition to a Silver Mage, you will want the storm trident, a Netcaster/Entangler, plus one more leveled unit to be fairly sure to knock him out in one round. Quick striking like this you end up fighting a lot less undead. You probably end up foddering one of the mermen to the Undead Archers, but the trade off is well worth it. You can keep cycling your mermen up to fight with any orcs or trolls that come into the water. Silver Mages can assist, since they are not needed much in the other part of the fight.
# After the undead leader is assassinated and the first wave is broken, you may advance cautiously due north or to the northwest along the coast and ultimately finish off the two orc leaders.

Spoilers...
* When you are close to the break in the woods at the east board edge, tighten your formation and keep wounded units well away, as a small force of high-level Saurians will appear. Trigger them in daylight if possible, and knock them out fast. Alternatively, you can delay triggering the Saurians as long as possible by moving your force northwest near the water and then onto the small island, though even then it is possible to trigger the Saurians if you are not careful where you step. (Stepping to 10 hexes or less from 34,15 triggers the Saurians.) You can fight the final wave of orcs from the island, then move northeast to the mainland, finally triggering the Saurians.
* Two cuttlefish appear when you approach the north-central island. Assuming you're sending a strike force through the water to knock out the undead commander, you really don't want to trigger these until that force is on the island - the storm trident Merman is the only thing that can stand up to them in water, and they will avoid him to attack more vulnerable units.
* Once you kill one enemy leader, the other gets more gold & recruits a new wave of L2s. This can be useful if you need to kill off surplus L1 units to improve the finish bonus, or if you need the XP more than the gold; otherwise, try to knock out both leaders on the same turn before they can recruit more. Alternatively, if you kill the first one at dawn, the second will be reluctant to attack with his L2s in daylight, and you might jump in and kill him before he uses them.
* Heads up: The next scenario is the final one. Therefore, loyal units are now somewhat disposable. However, you will need plenty of gold. Recruit some Peasants in the current scenario if you need to save some gold. Not only are they cheap, but they have no upkeep and Chocobones love 'em. Send a unit with leadership with them and they can even deal some amount of damage and be used to finish off wounded enemy, though at night you should just let them take the beating passively since otherwise they die too quickly.

===Rise of Wesnoth===

It's the final battle: be patient, recall everybody - the early finish bonus doesn't mean anything. Also, loyal units are no better than other units after your recruitment is finished.

Recruitment...
* You will need at least 300 starting gold, maybe more like 400 on the hardest difficulty level, so if need be, replay the previous scenario.
* To stretch your money, start with loyal Iron Maulers and a couple ready-to-level level 1's and level 2's. Finally, recall as many level 3's as possible.
* Healers: 3-6 Mages of Light / White Mages. Your few chaotic units will appreciate a White Mage.
* Horse units: 2-4 Paladins, 3-4 Knights / Grand Knights.
* Horse escorts: about 3 speedy units, like Royal Guards, Fugitives, and Silver Mages.
* Tanks: at least 6 high HP units, such as Royal Guards, Highwayman, Master Bowmen, and the loyal Iron Maulers.
* Mages: at least 3 high level Mages aside from your basic healers, so Arch Mages, Great Mages, and Silver Mages. Additional Mages of Light can be substituted.
* Some Mermen might be useful here, but surprisingly, they're not really necessary.
* On 1.9.3 and earlier, you can recruit Saurian Skirmishers on medium and Skirmishers plus Ambushers on hard. This appears to be a bug, so ignore the option.

Strategy...
* You will launch a two pronged assault: mounted units will race to the west and then south, while the main army heads due south.
* With your mounted units, race forwards by day and backwards by night.
* Along with the mounted units should go some escorts, speedy foot units intended to kill things like Goblin Impalers, which make even Grand Knights nervous. They would also benefit from a quick Mage of Light.
* Meanwhile, with your tanks and the rest of your healers and support units, form a line or hedgehog in the woods just south of your keep or next to the river.
* Keep your leaders with the main army, to avoid drawing too much attention to the mounted detachment.
* Maintain awareness of the overall battlefield. If the main army gets in trouble, you can send some or all of the mounted units to assist. There may be an opportunity to hammer-and-anvil enemy forces trapped in the middle. And you may wish to transfer units, like Paladins may be useful to the main army after it is on the move.
* You'll need at least two Paladins to kill Jevyan himself; nothing else is half as effective (except perhaps Mages of Light and suicidal Lancers). Or you can use a pair of Great Mages (unless you are very unlucky, you should be able to kill him in a single turn). Don't forget to sacrifice Aethyr to Jevyan. If he doesn't want to come out and play, march up to Jevyan and use a crossbow attack. When Jevyan is dead, the yellow and green leaders may still be alive. You'll have to kill one, leaving at least one orc leader alive. You pick. Congratulations! Enjoy the ending!

Spoilers...
* When one of your units is within 8 hexes of a bridge, but you have no units within 2 hexes of the bridge, and there are no units on the bridge, then a Cuttle Fish will appear and destroy the bridge. This is usually disadvantageous. Not only does it leave you with a Cuttle Fish to fight, but it slows your progress south and the bad guys progress north. At least on the hardest difficulty level, it's hard to kill all the spam in time, so you don't want to impede their advance by removing the bridge.
* When any of your units is killed, it becomes a Walking Corpse. On hard, it becomes a Soulless, which makes it important to be careful with your level 2's, especially Lancers.
* After the first orc leader is killed, then some gold goes to mister Lich. It's 40, 80, or 120 gold, for easy, medium, and hard, respectively. The lich will receive some gold once you kill his Familiar.

== See Also ==

* [[MainlineCampaigns]]

[[Category:Campaigns - The Rise of Wesnoth]]
[[Category:Campaigns - Walkthroughs]]

TheRiseOfWesnoth

2013-06-17T20:09:41Z

Anonymissimus: /* A Harrowing Escape */

== Strategy Guide for The Rise of Wesnoth Campaign ==

===Campaign strategy===

Over the course of this campaign, you will need to level up to some:

* Healers: White Mages/Mages of Light (at least four)
* Undead killers: Paladins (two)
* Mobile strikers: Silver Mages (at least one, preferably more), Grand Knights (several), Fugitives (one or more helps)
* Damage sinks: Royal Guards, Iron Maulers, Highwaymen, Halberdiers, level 3 Burin, and again Grand Knights
* Leaders: level 3 Haldric, level 3 Lady Outlaw, and much later level 3 Commander Aethyr
* Ranged attackers: Great Mages (can use several in the last scenario), Longbowmen/Master Bowmen (two), Trapper/Huntsman (one is helpful)

A Mage of Light, one Paladin, and five Grand Knights make a perfect assault team!

Although Horsemen are key for the first three or four scenarios, it's important not to be too reliant on horse units through the middle part of the campaign, as there are many hard levels underground, in swamps, in water, or against Saurians; use XP from the scenario ''The Vanguard'' to get to 2 Paladins and 2+ Grand Knights.

Don't overlook Pikemen/Halberdiers, which are useful in many levels; pierce attacks work well against Drakes and against the dragon, and they are handy for defensive roles especially repelling Wolf Riders. They are less good against undead, though, and don't get that +1 MP Royal Guard speed bonus.

Due to many undead opponents, you will want to recruit many Thugs at times, and get a few (the quick ones, since you need them underground) leveled up. Footpads help too, once leveled up. Due to swamps, you will sometimes be spamming Poachers, which get marksmanship once at level 3. These, plus Lady Outlaw, give tactical options at other levels too: some decent chaotic troops form an ideal reserve, since you can attack with your lawful troops at dawn, and by nightfall when you need to heal them, use some chaotic troops to either continue the attack or to shield your healing lawful units.

Here are some recommended units to have obtained by specific scenarios:

2. The Fall - 1 Knight 
3. A Harrowing Escape - 1 White Mage, 2 Knights, plus about-to-level troops 
4a. The Midlands - avoid, go to The Swamp of Eden instead 
4b. The Swamp of Eden - level 2 Haldric, level 2 Lady Outlaw, 2 Knights, 2 Shocktroopers 
6. Temple of the Deep - level 3 Haldric, level 3 Burin, 1-2 Mages of Light or several Outlaws / quick Bandits 
8. Clearwater Port - level 3 Lady Outlaw, 3 White Mages / Mages of Light, 3 Iron Maulers / Royal Guards / Halberdiers 
12. A Final Spring - 1-2 Silver Mages 
14. Rough Landing - the 3 loyal Mermen from the previous scenario, ''Peoples in Decline''[glandis] In 1.8.6, there was no opportunity for 3 loyal mermen - maybe this was in an older version? And only Merman fighters can be recruited - no Netcaster upgardes are possible 
17a. The Dragon - up to 4 White Mages / Mages of Light 
17d. Cursed Island - 1 Paladin 
19. The Vanguard - 4 Knights/Lancers/Grand Knights, 2 Paladins (or about-to-level Knights) 
20. Return of the Fleet - 1 Mermen Entangler, 1 Merman Triton with Storm Trident, level 3 Commander Aethyr desirable 
22. The Rise of Wesnoth - 2 Paladins, 3 Royal Guards, 4 Mages of Light

Because the campaign is long and you won't be able to recall all your level 3's in the final scenario, it pays to create some "uber-units". An example is a quick, resilient Silver Mage that has been AMLA advanced a few times.

==Scenarios==
===A Summer Of Storms ===

This is a relatively easy scenario, so gear your recruitment and strategy with an eye towards gathering XP.

Recruitment...
# For the first round, recruit 2-3 Horsemen and the rest can be all Spearmen or a mix of Spearmen and Bowmen as you see fit.
# Then, you should probably hire Bowmen and more Spearmen. Whatever Bowmen you can get advanced will be useful later on for fighting the many trolls, grunts, and riders you will encounter. Note, however, that you will not have any healers until you level up at least one mage to White Mage status, and the sooner you can do that the better. Red mages will also prove very useful in subsequent scenarios, so consider recruiting at least two mages.

Strategy...
* Players have used at least three strategies with success...
# The "over the bridge" strategy: Send the horsemen with the king over the bridge, and the others should follow or start going over the mountain, to avoid being attacked from behind. Send subsequent Spearmen and Bowmen on the "over-the-bridge" road, and when the Prince and final troops have just about caught up, march on the enemy camp.
# The "hide in the swamp" strategy: Proceed much like the above, but send the king with 3 Horsemen to capture the nearest houses, then retreat into the swamp area until you have your lawful bonus to kill off troops during the day. To hold them back, you can use a Spearman and a Mage (to level him.)
# "Sandbagging" strategy: On the hardest difficulty level, the initial enemy assault will only be easy to handle by entrenching your troops behind the river. Use the king to block the bridge initially, while Spearmen handle the shoreline just north and Horsemen carefully flag villages across the river. Run the king around, lending his leadership as you massacre the stupid enemy troops that have jumped like lemmings into the water.
* For all these options, you will also need to send a squad north into the mountains and around into the flank of the enemy. A quick Spearman, a quick Bowman, and one other unit, possibly a quick Mage, should be more than sufficient.
* When you see that the fronts are under control, stop recruiting and send prince Haldric and your Mages over the bridge on a quest for XP, assisted by the leadership of the king, and converge on the enemy camp.

===The Fall===

This is a scenario that looks scary, but it is only moderately difficult with proper recruitment and strategy.

Recruitment...
* Recall or recruit Spearmen and Bowmen to man the lines.
* Horsemen/Knights are desirable, because you probably do not yet have a White Mage, and the villages are widely spaced.
* Recalling or recruiting Mages for XP gathering is highly advisable for future scenarios.

Strategy...
* There are three basic approaches to take out the outlaw leader...
# "Brute force" strategy: You can march west with a large army and use part of it to hold northwestern orc. Use the rest to fight outlaws and kill the leader. This strategy requires a lot of troops but it can bring you plenty of experience and can bring a quick victory.
# "Assassination over the bridge" strategy: You can assassinate the outlaw leader. One way is to wait until the orcs have killed almost all outlaws and then assassinate the outlaw leader with Knights, rushing over the enemy camp's bridge and into the keep. This strategy is risky because orcs can kill the leader before you.
# "Assassination via the mountain pass" strategy: Another way to assassinate the leader is to send a squad through the southern mountains to the outlaw keep. Two Mages and three Spearmen are enough. You may wish to substitute one of the Spearmen with a Knight or Horseman, though horse units have only a narrow passage devoid of mountains and could get pinned by the enemy.
* On the hardest difficulty level, you may be forced to assassinate. For either of the assassination strategies, it is a good idea to fight against the northeastern orc nearby your keep. This way, you can secure your back and earn experience.

Hints...

* Saving the loyal Heavy Infantrymen (or Shock Troopers on easy) pays off in later scenarios. To save all three, move them south towards the outlaws.

* Once you eliminate the HP of the Lady Outlaw, she offers to help you. If you say yes, she comes back as a loyal unit in future scenarios and you will be able to recruit outlaw units, plus she cannot be killed in the next couple of scenarios (instead, she disappears when she goes to zero HP, and comes back the next scenario.) This is quite valuable. If you say no and try to kill her, you find out she cannot be killed. However, you do get 200 gold that she leaves behind.

* Heads up: The following scenario (''A Harrowing Escape'') is a handful on the hardest difficulty level. On hard, a carryover of almost 150 gold (so you have 250 starting gold) would be wise, so although Lady Outlaw's assistance is worth much more than 200 gold, you may be forced to choose the gold. Another thing you need to beat the following scenario on hard is a White Mage at or near the start of the scenario. Also, about-to-level units will be especially nice for their self-healing ability and low initial upkeep. Steer XP accordingly.

===A Harrowing Escape===

This scenario is much easier on lower difficulty levels, calling for different strategies.

On easy/medium...
* Recruitment: You should recruit/recall at least one, possibly two Mages here, and use them for killing Goblin Spearmen and finishing off injured Wolf Riders in the hills & mountains bordering the valley. Other than the Mages, simply recruit what you want, and go along the road. You get enough villages to pay upkeep for quite some army, and can give some of them a bit of experience.
* Strategy: Leave a few units in the rear, as the enemy can cross hills quickly. Note that Footpads and Outlaws will also cross hills at reasonable speed, if you need to hunt down some units. There are two castle tiles about halfway down, try to send Lady Outlaw and Brunin the Lost to them, they make good guards in case the enemy tries to come straight up. You can also send a couple groups of units down southeast to the lake, so you can prevent the Green team (southeast) from coming up the river. You can also kill the two Orcish Grunts (or Warriors on medium) on the southern castle tiles and then move Lady Outlaw and Brunin to them.

On hard...
* Recruitment: To beat this scenario on the hardest difficulty level, you need some level 2 (or better yet, about-to-level level 1) units already and a lot of starting gold. It is possible with ~200 starting gold, but only barely. 250+ is better. You can stretch your gold a bit by not going negative on upkeep and waiting until you can't wait any longer to do one last round of recruiting, recalling mostly level 2's. For timing your final recruitment, watch the wolves that are likely trying to flank through the mountains south of your keep. Another requirement for beating this scenario is a White Mage (or two.) If need be, you must promote a Mage (or two) tout de suite, as you will be dealing with severe damage and assassins, while only having easy access to 2 or 3 villages initially. Horsemen and Knights are useful for dissipating damage by serving as meat shields against blades and then running off to remote villages to heal. Quick Horsemen are especially nice, as they can transfer between two strategically placed villages in one turn, for healing on the go. Horsemen, Knights, and Swordsmen are useful for swatting assassins.

* Strategy: More important than terrain is avoiding getting flanked, so mobility of individual units is key; if you climb up deep into the mountains, you will have a harder time with mobility than staying on or near the valley floor. Additionally, many of your units cannot go on mountain hexes, so it's easier to maintain your lines if everyone stays close to the valley. Near the start of combat, it's crucial to kill units quickly on the road: first the wave of wolves, then the wave of assassins. In contrast to easy and medium, on the hardest difficulty level both pairs of roadside castle tiles are guarded, not just the second pair. As on medium, the guards are Orcish Warriors.

Hints...
* On medium/hard, you can lure out the roadside guard Warriors one at a time by putting a unit within attack range of one (and out of range of the other.) They mostly come at night. Mostly. That is, the Warriors might not bite bait put out during the day.

* If you have Lady Outlaw, note that she has leadership, which will be useful to help promote Prince Haldric, if he is still level 0. It's worth advancing her to level 2, to continue to provide leadership to level 1 Haldric and your other level 1's. You may also make use of her odd ability "distract", which allows adjacent allied units to ignore ZOCs. And Lady Outlaw allows you to recruit outlaw types. On hard especially, Thugs can be useful as meat shields and to provide strong attacks at night when your lawful forces are crippled. Remember too that Lady Outlaw cannot be permanently killed (at least not yet), so when desperate times call for desperate measures, you can move her into a suicidal position.

Spoilers...

* The scenario can be beaten on hard with 154 gold only (I decided to trust the lady). Key points in the strategy I used:
** Underrecruited as heavily as possible, so that the upkeep of my current units was completely offset by my villages. Only 2 footpads to go for Burin and villages down the path right at the start. Only level 2 unit I recalled initially was a white mage. Recalled the 3 loyal HI and tried to arrange it so that they aren't attacked by archers. Recruited several thieves, since they are cheap and the grunts are font of attacking them instead of my mages (and they still often survive on 70% def).
** During the main phase of the battle, stayed on the safe side of the river (this was the actual key point). Used the river, mountains, castle and swamp to have good defense for myself and bad one for the orcs. As shortly as possible before my income turned negative, recruited/recalled an additional 5 units. Needed to give up the village abroad the river as well (so only 3 villages left).
** What also helps as well is the fact that there are two enemy sides as opposed to a twice as strong single enemy side. If one of your units could be attacked by 3 enemies, but 1 of these hexes is currently blocked by the other side, the currently moving enemy decides to attack units which it (they) is (are) actually less likely to kill than that one. AIs don't cooperate, that is.

* There is Dwarf Steelclad in the village at 8,5. It's not far from your camp, so send Lady Outlaw there. Dwarf joins you because "It has been a long time since he felt the satisfying crunch of Orcs under his Axe."

* After you kill the first orc leader, an Orcish Slayer and two Assassins will pop out of nowhere, so you would be wise not to have any wounded units stuck without movement points at that point. Also, the other leader will get an infusion of gold and start recruiting on all available hexes, so if you can sit on some of those hexes first, it will help keep the situation from getting out of control.

* At the end, you will be given the choice of the river/swamp road or the midlands/orc road. These fork to the scenarios ''The Swamp of Esten'' and ''The Midlands'', respectively. The swamp scenario is relatively easy, while ''The Midlands'' could cost you some leveled units or even prove impossible to beat if you are low on gold. Also, the swamp gives you a free loyal White Mage, so it's a no brainer, unless you want more of a challenge.

* Heads up: it would be wise to have at least 1 Mage either levelled up to White or about to level up before going to the scenario ''The Swamp of Esten''.

===Diverging Campaign Path===
====The Midlands====

Orcs again. But you chose that way. This scenario may appear impossible, but with a lot of gold and a little strategy, it can be beat.

Recruitment...
* You are given plenty of time, so use it wisely. The enemies send lots of orcs, mostly weak ones. So recruit and recall everything you can.
* Recall any White Mages you have. You'll need them.
* Bowmen are good for the wolf units you will be facing.
* The rest depends on your strategy.

Strategy...
* The "Fast Assault" option: use an assassination team. If you go west, only your Knights and Horsemen will arrive and fight at daytime. So go south. Take the bridge and defend against the enemy closing in from the west. Take out Yellow with a fast assault team (they should take a healer along), but be careful about the leader. Your main force moves west, takes and holds the second bridge, and takes out Blue. Your assault team stays in the south and goes for the last enemy leader - they won't face any serious resistance. The enemy moves north to support Blue. The HI guarding the bridge might gain a level or die, but hopefully not the latter, as they are loyal units in a long campaign. With this approach, you can finish early (around 25 turns) and keep your losses low.
* The "Dark Assault" option: use Footpads. If you chose to work with the the outlaws in the last round, then this works well. Footpads are cheap. And they are fast. And they have good defensive abilities. Plus they fight well in the dark and in the forest. So recruit lots of Footpads-pawns and quickly dispatch them to the upper west and south, followed by more powerful units: Mages, Horsemen, etc. For the time being, leave the middle enemy alone. To the upper west, send several Footpads into the forest and capture the village and set up a defensive line. This cuts down the enemy's gold and increases yours. Don't attack at first, just defend, until more of your slow higher powered units arrive. The strategy here is to pick off the orcs, and send the Horsemen to capture villages. While this is going, to the south you send your Footpads to capture any villages you can and, more importantly, put a Footpad on the hex that is adjacent to the bridge, thereby stopping easy advancement of their greater numbered troops. A White Mage, a couple Trappers and some Bowmen would make a good escort. Probably sending a Thief or two would be good too, to help dispatch any enemy that infiltrate the villages north of the river. one enemy got into one of the villages on the north of river, and it took a lot to dislodge him. The intention is to engage the enemy so that they are fighting from the river squares, at a huge disadvantage.

====The Swamp Of Esten====

This scenario is not too hard if you are conservative and don't send important units off alone.

Recruitment...
# First round, recall 1-2 quick Knights (or Paladins, if you have them), recruit 1-2 Horsemen, and recall your loyal Shocktroopers or whatever they are now.
# Next round, recruit/recall Mages to kill Scorpions (and Bats) and at least one White Mage to deal with poison, plus maybe a Poacher, as they are good in swamp (and you would like a Huntsman eventually, for its markmanship.)
# A little Thug spam can come next, but you don't need a full third round of recruitment. Then send Prince Haldric off to lend his leadership.

Strategy...
# You must blitz the northeastern leader, or risk getting bogged down on bad terrain facing a swarm of undead spam, which can be nasty at night. Quickly send Knights (or Paladins) and Burin over the ford to start wailing on undead. A disposable Horseman can try to take out Scorpions in this area at first. On the way is your proper Scorpion disposal unit, the Mages and White Mage. Try to kill Dark Adepts with Burin or horse units before they have chance to attack you. As you close in on the leader, hover your mouse over him to watch where he can go, as his ranged attack is nasty and can be followed up by waves of kamikaze Walking Corpses, which can take out a Knight.
# After you have killed the northeastern leader and eliminated troops there, you can either send your whole army back across the ford and south or split your army into two halves, sending one part to each leader. If you have lost several units but have lots of turns left, it's probably safer to stick together. This is not a simple mop-up operation, as powerful undead can take out some of your valuable units if you're not careful. On hard, Shadows are a constant threat at night.

Spoiler...

* Searching the temples is a good idea. Some have gold. There is a free loyal White Mage hiding in (a random) one of the temples - visit the temple close to the keep ASAP, and if not there, try rushing a horse unit or Lady Outlaw to the temple at 19,5. However, some of the temples contain undead, so keep extra troops nearby when you enter one.

===The Oldwood===

This is a relatively easy scenario.

Recruitment...
# First round, recall your (probably leveled up) Heavy Infantry from The Fall and some quick fighters.
# Second round, recall White Mages and quick Mages.
# Third round, round out with Thugs, Bowmen, and Spearmen, preferably quick.

Strategy...
* Your forces will have three main combat arenas: the northeast, the south, and the middle.
# The main bulk of your force, including at least one White Mage, should head east to the orc in the northeastern castle. The leader there recruits a lot of units, and most of them are level 2, so watch out.
# Haldric, a White Mage, your loyal Heavy Infantry types, and a couple of level 1's (maybe a Mage and a Thug) should head south to the other orc leader. A few effective melee units can easily counter the riders they send early on, and then with a little forethought and patience you can take out their Archers and Crossbowmen without giving them time to shoot.
# The castle in the middle is inhabited by the tree folk, so don't bother sending troops there; however, you might want to keep a couple speedy units not far off to watch their backs, in case the allied leader gets into trouble, as is usually the case.

Spoilers...
* The temple contains the entrance to the catacombs, but you need the leader Wose's help to open it, and to get that help you have to win the current scenario, so there is no point in visiting this temple.

* Heads up: The next scenario is in the catacombs, i.e., underground, and it's a tough one, so you need to groom your roster accordingly. Two Mages of Light would make it a whole lot easier. Failing that, level up your fearless loyal Shocktrooper and chaotic outlaw types. Bandits/Highwaymen and Fugitives are especially nice. Quick units of almost any type (except horse units) will be helpful, if leveled and possessing high HP (>50).

===Temple in the Deep===

You will be facing undead underground. This is a difficult situation that will prove much easier with proper recruitment. Then the strategy will be fairly straightforward.

Recruitment...

* All in all, what you need is a small elite force. Two rounds of recalls is enough, if you didn't lose Burin in a prior scenario.
# First round, recall your loyal Shocktroopers / Iron Maulers, especially the fearless one, though their slow movement will prove frustrating. Also on the first round, recall a fast "tank" and someone to grab the holy water (if Burin is not your choice.)
# Second round, recall any Mages of Light you might already have, and a total of at least two White Mages or Mages of Light, preferably quick. For the rest of your recruitment, what you need are high movement (6+ MP) non-horse units with high hitpoints (>50 HP), preferably chaotic, preferably with a ranged attack, and preferably impact attacks. Put all the requirements together and it points to Fugitives. Outlaws and quick Arch Mages are worth recalling too. Fill out the rest with Bandits/Highwaymen, Trappers/Huntsmen, and Longbowmen/Master Bowmen, preferably quick. You might think that Red Mages would be good, but they attract melee attacks that they likely will not survive. Note that Horse units are too sluggish to be useful here and should not be recalled/recruited.
# Third round (optional), you can add a unit or two for a safety margin.

Strategy...

# There are two ways north, but they will meet up together before you meet any enemies besides the Tentacles. Ignore the tentacles for the most part and only kill them when it's convenient, as you will need to have a strong line set up by the time you engage the undead. Watch out for the enemy's Bone Shooters, Revenants and Deathblades, as they could easily mess up a level 3 unit. Once you see the two choke points, hold them so one of their units is facing 2 of yours (preferably with a White Mage behind them). You may be able to level up a White Mage to a Mage of Light while fighting in the choke point. If your troops are too slow to grab both choke points, you can send Burin and others to the west choke point while your slow troops line up at the southeast shoreline and bridge.
# Gradually progress northwards once the flow of baddies has tapered off, and once you get into the final chamber, the boss should be a piece of cake, although his ranged attack is devastating, so try to attack him with melee units. Be careful if he has recruits around, as their combined damage can take down one of your level 3's. Note that the Ruby can only be picked up by Haldric.

Hints...

* Holy water: Burin is very effective if you give him the holy water; however, it's more helpful to send Burin running to the west choke point without delay. A good alternative is a Highwayman - or a Bandit, who should level quickly. Compared to a Highwayman/Bandit, Prince Haldric or a Royal Guard is not that great a choice for the holy water due to their lawful alignment and -25% penalty, unless you have (or will soon get) a Mage of Light.

* XP: Use this level to get experience. The early-finish bonus is tiny. The tentacles are perfect for leveling up units. If you're hurting for leveled chaotic units, you can even level up two raw recruit Thugs (use Haldric's leadership to assist). Keep Burin away from the water at this stage, or he'll kill all tentacles as they attack, depriving those who could benefit from the XP.

Spoilers...

* Your killed units will be turned into Walking Corpses (or Soulless on hard.) Therefore, spam is not helpful. A Mage or two can be okay, if used with great care, but mostly you need to recall leveled troops here.

===Return to Oldwood===

Plot only.

===Clearwater Port===

This scenario is easy if you take the first boat out, more and more challenging for the second and third boats, and very difficult (on hard) if you want to take out all three leaders.

Recruitment...
# First turn, recall your loyal Shocktroopers / Iron Maulers from ''The Fall.'' You will also want several Footpads, for speedy village snatching, coastline defending (under leader supervision), and possibly for filling castle hexes if your lines get too thin.
# Second turn, recruit/recall more low maintenance units. It's a good scenario for leveling troops, so recalling acouple half-leveled Spearmen or similar is a good idea.
# Third and later turns, start recalling your high maintenance units. The key to winning this scenario is to recall several advanced units that can take a lot of damage and get good defense in castles (no Horsemen). You will also want at least 3 White Mages or Mages of Light.

Strategy...
# Backstab your ally, stealing all his villages. Your ally is useless anyway, except for the entertainment value from his troops' suicide runs. The income is much better in your hands.
# Send your heavy duty troops with some White Mages over to the line of castle near Lt. Aethyr. (Optionally, you can rush forward past the castle, but you will need to return almost as quickly before the main enemy wave and night arrive.) Aethyr will usually be done recruiting by the second or third turn, before the enemy reaches you, so fill the entire line with your units, and put Knight Sir Rudry in the one non castled tile (or leave it empty, if no enemy are adjacent.) Place the White Mages behind this line. After the enemy has reached you and it is your turn to attack, go mostly for the assasins, as they have a weak melee attack and their poison can be a huge problem.
# Meanwhile, on the northeastern coast, the northern enemy leader will send lots of units to catch your flank unguarded. Send 2 Footpads, a Spearman, Lady Jessene, and Haldric to guard the coast. If Lady Jessene is already level 3, you can substitute a Royal Guard, Swordsman, or Javelineer for Haldric. This coastline defense squad may need help later, so be ready to divert a speedy powerful unit there. If you keep a healthy unit on the village at the tip of the land, then, unless you are very unlucky, you will be able to hold off everything the northern leader sends. After the assault from the water has been crushed, some of your troops may be able to cross the ford north, but be careful not to get attacked in the water with only 20% defense. (Certain of your chaotic units do have 40% defense in water; now is a good time to pay attention to that.) Also, notice that the lighthouse has a similar effect as a Mage of Light.
# You have two options for the endgame:
## "Total victory" strategy: Once you've thinned the enemy to where they only have a few units that are close to your line, usually this happens conveniently around dawn, move your people out and start heading for their leaders. Split your force, sending a few down the southern path, to distract the eney and most of them toward the middle leader, to kill him. Once he's dead, send some of your army down to kill the southern leader and devote a few units to defending the bridge until the rest of your army can rejoin you. A unit or two with a lot of HP with a white mage are usually enough to do this.
## "Run like hell" strategy: Alternatively, you can leave your leader near the docks and take one of the boats to end the scenario.

===Fallen Lich Point===

This is a high variance scenario. It may be very easy or very hard, depending on events beyond your control.

Recruitment...
* Recruit fairly lightly initially, as you will likely have a chance to use the Lich's keep to recruit again.
* Mages, White Mages, and Mages of Light are good, and as are all the other advancements of Mages.
* You automatically should have your loyal Knight. Because of the mountains around "lichland" and frozen ground everywhere else, additional horse units are not recommended, except a single Paladin will come in handy.
* Some Thugs or a Bandit or Highwayman will provide a little extra undead bashing power.
* Footpads will help with village flagging, after the Wolf Rider types are taken care of, but you can postpone buying Footpads until after killing the Lich.

Strategy...
# The Orcs will be busy with the Yetis, so you can walk with a big group south and kill the Lich-Lord. Move Haldric to the stone monument to de-petrify the Lich. It may help to post some units around the undead before doing so. Use several mages to make a hole or two in the ring of undead, and then push in a burly fighter or two and/or Paladin to kill the Lich.
# After killing the Lich, assess the Orc/Yeti situation (as well as the empty village situation) and decide if you need to use the Lich's keep to recruit some reinforcements.
# After that, head north and walk into the sewer entrance (the "cave") or else kill the orc leaders.

Hints...
* It is also possible, if you recruit heavily, to split your force and head north to attack the eastern Orcs before they finish with the Yetis. However, be careful not to be attacked by a Yeti yourself; a Yeti is dangerous even if heavily wounded. A Yeti will attack you if it can get to a unit within one turn (and it doesn't have a more appealing orc target.)
* When dealing with the Lich, be aware that he has money; if you let him vacate any of his encampment tiles, or if you kill any of his units but do not occupy their tiles, he will be able to recruit. (This is not necessarily all bad, as it can mean more experience, but depending on the strength of your force you may want to be careful.)
* Note that this level becomes a lot tougher if the Yetis get poisoned early on and quickly die. If this happens you basically have no other choice than to kill the orc leaders first.

===Sewer of Southbay===

This is a swampy underground scenario, but with attention to recruitment, it's not very difficult.

Recruitment...
* As always underground, you want non-horse units with 6+ MP.
* Recall White Mages / Mages of Light, at least two, three is probably the optimal number.
* There are quite a few villages in this cave, so an expensive force is supportable, though not necessary. Some players recruit a large and spammy force, while others go with small and elite:
** Option 1, "Large and spammy" recruitment: Recruit four each of Mages, Thugs, and Poachers. Yes, Poachers normally stink, but here they really shine in a swamp that is permanently dark, underground. If you recruit four Poachers, you could finish with three Trappers and a Huntsman - or you could finish with four dead Poachers. The Thugs are especially likely to die, as they will be facing off against Red Mages, but somebody has to do it.
** Option 2, "Small and elite" recruitment: Recall something like one Red Mage, one Arch Mage, one Silver Mage, 2 twooyal Guards/Highwaymen/etc, and a Trapper or Huntsman, plus three regular Mages and a Poacher.

Strategy...
# After leaving your initial chamber, you will be in a large swamp room with three entrances, through which will be a flood of bad guys. Use two Poachers and a Thug or similar to blockade the southeast, a small elite group to block the north, and then a mix of fighters and mages to handle the west entrance. Give each group a White Mage or Mage of Light, as well as at least one regular Mage. Try to keep the Mages of Light away from your chaotic forces on the front lines, though. Use the leadership of Haldric and Lady Jessene - and Mage of Light illumination or lack thereof - to get the most from each attack.
# When the initial battle has died down, you have two options:
## If you have enough forces, you can divide into two groups and attack both brothers simultanously, east and west.
## Otherwise, do them one after the other, and then look for the exit.

Spoilers...
* Danger: there is a Giant Spider at the exit. You may wish to keep one or two cannon fodder units in order to be able to save your advanced units. It is best to use ranged attacks against the spider, so leveled mages are good here.
* Heads up: the next scenario is a lot easier with a lot of gold, especially on the hardest difficulty level.

===Southbay in Winter===

Plot only.

===A Final Spring===

This is a large battle, and any mistake on any front can spell doom, but overall it will be fairly easy on the easier difficulty levels. On hard, it will only be a cakewalk with a lot of starting gold (more than 450 or so.)

Recruitment...
# On the first turn, recall a Silver Mage to teleport to the island, recruit Footpads for village snatching, recall one or more of your loyal Iron Maulers (leveled up Heavy Infantrymen from ''The Fall''), and recall one or more Knights or similar.
# Second turn, continue with this theme, but it will be nightfall soon, so recall Outlaws, Bandits, Assassins, etc.
# Turn three is a bit more of the same, but you need to start thinking about preserving your income and also keeping a gold reserve. You can spam some peasants to preserve cash and income.
# Turn four turn is more of the same.
# Turn five is similar, but it will be day soon, so lawfuls like Knights and level 1 Mages are a good idea.
# Turn six, you will have new recruitment options (see spoiler at walkthrough end.)

Strategy is broken into four fronts...
# The first front is the south land area. Do a counter-clockwise sweep with mounted units, optionally augmented with Footpads, which can help pad out your lines with forest and village hexes. Note that it will be nightfall soon after game start, so it might be wise to delay any serious mounted assault until the next day, and you can delay your recalls for this.
# The second front is the walled city. Move slower units and your loyal White Mage / Mage of Light to defend here. Take your ally's villages; your ally wouldn't do much useful with the money anyway. When your mounted units from the second front complete their sweep, you can break the remaining southern forces against the city wall in a hammer and anvil. Then your united forces can move north. On easy, you may be able to push north more quickly than that using just part of your city troops.
# The third front is the bay and peninsula north of your keep. If you don't protect this area well, Wolf Riders and others will mount an amphibious assault in an effort to flank your troops. On the easier difficulty levels, you may wish to beat the punch and quickly establish a bridgehead on the other side of the bay.
# The fourth front is the two small islands. Send a Silver Mage there ASAP. (You should have a village already there, so the Silver Mage can teleport over.) Footpads/Outlaws/Fugitives and others will help later. Lady Jessene could be used. A quick White Mage would be useful, either on the coast or on the islands. Do not use Assassins on this front. Assassins have relatively weak defense in water against Orcs and Nagas, they're very weak against blade, which is all orcs and nagas use, and their relatively slow movement in water makes backstab hard to use reliably. Overall, you need to devote more resources to this front than you might think.

Hints...
* You should have lots of high-level units now, so concentrate on recruiting new ones and levelling them up to fill needs.
* Peasants are useful as placeholders for villages and distractions for the enemy.

Spoilers...
* On turn 5, a gang of nasty undead show up in the east. So, for your city taskforce, you'll want to recruit/recall units with impact and arcane attacks. Note that if undead capture villages, they will be flagged with the Orc island boss' black flag! This can result in an overwhelming number of Nagas, and it's one reason that you must devote a lot of resources to the island campaign. Flag any black flag villages you can.
* On turn 6, a gang of nasty Mermen show up in the west. Fortunately, they are on your side. You can now recruit Mermen. This is the real reason to keep a gold reserve until this time.

===Peoples in Decline===

This is a bloody scenario versus Drakes. It can be a real challenge on the hardest difficulty setting, less so on the easier levels. Proper recruitment is more important than strategy here, as you will have little opportunity to maneuver.

Recruitment...
* Drakes can be dangerous, so this is a great scenario to use the time honored technique of cannon fodder. Now that you can recruit level 0 units for cheap, you can protect your higher level units by recruiting endless Peasants to distract the Drakes' firepower.
* Drakes are vulnerable to pierce attacks, so spam cheap pierce attack units. In addition to Peasants, there are Poachers, Bowmen, Peasants, Spearmen, Merman Fighters, and Merman Hunters. Poachers are key here, due to the swampy terrain and their chaotic alignment.
* You will need about 3 White Mages / Mages of Light in all.
* On your last turn of recruitment when you have about 80 gold, recall some advanced units, like Master Bowmen.

Strategy...
* Since you will have a lot of level 1 and 0 units, make sure to use the leadership of Prince Haldric and Lady Jessene.
* Look for opportunities to heal via leveling up.
* Pay attention to the day-night cycle in this scenario. Drakes will be strong during day, but become very weak in the night.
* Take advantage of the mountains for defense, but note that on hard, you need to set up a relatively small perimeter around your base, as you will be hard pressed to even hold a small area.
* Be careful with your loyals.
* Because most Drakes have powerful ranged attacks, the roles of your melee and ranged units are reversed from the norm. Whereas usually you would use fighters to protect archers, here you will use archers to protect fighters. Melee-only units should hide behind the lines until they attack, preferably at night (with a Mage of Light supplying illumination.)

Spoiler...
* Make sure you get the Storm Trident in the middle of the sea, but be certain that you've cleared most of the Drakes first, since a Sea Serpent will appear. It's best to have some strong units ready to kill it in 1 or 2 turns. You can give the trident to Lord Typhon, but since he leaves a bit later, you may want to give it to another Merman Fighter. Movement over land is important for Mermen in the campaign as a whole. If the Merman Fighter to whom you give the storm trident has the Quick attribute, you can make him a Hoplite when he gets to level 3. Otherwise, make him a Triton, because movement over land is important for Mermen in this campaign as a whole.

===Rough Landing===

You will be fighting Nagas and Vampire Bats, primarily. This is a scenario that may be frustrating on the easier difficulty levels, though on hard it is just par for the course. Good recruitment and strategy will save you from getting slaughtered.

Recruitment...
* You are probably going to go negative on gold and be unable to rectify that with the paultry early finish bonus, so you might as will go very negative and be resigned to start the next scenario with minimum gold.
* Recruit/recall many Mermen and 1 or 2 White Mages or Mages of Light. A few Peasants can be useful to pad out your force, distract the enemy, and protect villages from stray Bats. A Silver Mage can be useful for island hopping but is not essential. Thieves/Assassins are blade vulnerable, and Nagas only use blades, so it's probably best not to recall them.

Strategy...
# Knock out the southeastern leader in a blitz. It's important to get that out of the way, because a wave of Nagas is advancing at light speed from the north.
# Next, hurriedly set up a line in the water alongside your fortress island. Your fortress troops can anchor one flank, while Burin the Dwarf can go to the island to the northeast to anchor the other end of your line. Nobody messes with Burin. Move Lady Jessene behind the lines to lend her support to the Mermen. Your loyal Mage of Light will be able to move back and forth more (to lend illumination) if kept in the fortress area.
# Finally, once the enemy assault wave has been broken, advance northward to kill the final two leaders in a straightforward mop-up operation. Just be careful not leave isolated units where they can get swarmed.

Hints/Spoilers...
* Try to level up the mermen; they can be useful in another scenario later.
* Beware of Sea Serpents. Three of them will appear, one on each of the three turns following your first kill of an enemy unit. Make sure to kill them at once. The Storm Trident from the previous scenario and the Ruby of Fire will come in handy against the Serpents.

===A New Land===

This is a non-scenario. The scenario objectives tell you to avoid all confrontation for as long as possible, but actually the faster your units encounter the others the faster the scenario will end.

Recruitment...
* None necessary.

Strategy...
* The optimal strategy for gold carryover is to grab the three closest villages, then retreat to your keep and wait. Once one attack occurs, the non-scenario will be over.

Spoiler...
* One thing to keep in mind is that this the last chance you have to grab some more Mermen as their king leaves. They are quite helpful in a later scenario so grabbing a few extra here cannot hurt if you can spare the gold.

===The Ka'lian===

Story, with your choice of four battles next. You have to beat them all in whatever order. The amount of gold you have should be the factor in deciding when you choose to play Cursed Isle (the undead problem).

===Diverging Campaign Path===

All four scenarios have to be beaten, but in whatever order you choose.
====The Dragon====

This scenario is not as difficult as it looks, though your recruitment and strategy need to be tailored to fight the Saurian Skirmishers and other foes you will face here.

Recruitment...
* Saurians use piercing attacks mostly, so it's better to use units resistant to pierce. Pikemen and Halberdiers have 40% pierce resistance. Javelineers are ideal as Saurians use ranged attacks a lot.
* You may wish to bench some or all of your loyal Iron Maulers. They are ineffective against the 70% impact resistant Mudcrawlers, while also vulnerable to the ranged attacks of both Mudcrawlers and Saurians.
* Consider adopting a force of all units with ranged attacks, save for horse and thief units, which can be kept behind the lines when not in use. It is amusing when Saurian Augers are forced to tap your units with their little staffs.
* Healers are a necessity to deal with the heavy damage your units will be sustaining. Depending on the strategy you adopt, you will want 2-4 healers. Mages of Light rock here, as they can easily do front line duty in pairs and their illumination blinds the Saurians, reducing their damage.
* You need something to clean up mud. Versus level 0 Mudcrawlers, Horsemen and their advancements can charge with no counterattack, and likewise Thieves and their advancements can backstab with no counterattack. Mages can be used as well on the fire vulnerable mud.
* A Merman or two will help with water hexes. An Entangler's slow ability will help tame the dragon.

Strategy...
* Players have used many different strategies with success:
** "Hedgehog" strategy: Fighting Saurians requires a disciplined formation. If you're used to stringing out troops to move them into position as they get there, that won't work after Turn 2 or 3. You can use a "healing hedgehog" of ten troops--two white mages next to each other and eight troops completely encircling them. If someone gets badly injured, move them to the inside and put a white mage on one of the long edges, fighting as you go. If you're trying for the big bonus, you'll need two hedgehogs. Try to keep reserves back a bit in cities. If the terrain favorably protects you, or the wounded is a fast unit, you can try moving wounded back to cities too. Once the main wave of Saurians is broken, you can string non-wounded troops out a bit in the rush for the leaders.
** "Triangular Hedgehog" strategy: Switching wounded units to the inside of the hedgehog can be a problem if you are surrounded. ZOC prevents you from creating an open hex to move the inner unit into. You can fix this by creating a triangle with three hexes inside, instead of the standard two of the hedgehog. If you do this on your castle, only three units are in grasslands. If you set it right, you can make most of the hexes adjacent to your triangle be grassland as well, forcing the Saurians into a bad defensive position. In terms of unit positioning, the simplest way is to fill two inner spaces with Mages of Light, a but a better tactic is to put one of the mages on an edge, thereby ensuring that all but one of your units are healing. The remaining unit can either be a Merman Hoplite, (prefereably resilient and carrying a Storm Trident) or Lady Jessene, since she has excellent defense and is chaotic and therefore benefits by not being in the Mages' light.
** "Giant Hedgehog" strategy: Recruit a lot of units, and then move the whole army as one big bulk. Keep healers in the middle (about four), rotate stronger units outwards, and make sure you leave no gaps. The Saurians will slip through the tiniest gap and kill your weak units. Head first for the east or wast leader, but steer for good terrain, because your force will soon be swarmed until about turn 10, when there should be many few Saurians alive.
** "Standard Line" strategy: Form a line from the west board edge diagonally up towards your keep across the two villages just in front of the forest. You will probably wish to bend upwards at the forest, rather than running the line all the way to the keep. Whenever the Saurians have a small number of troops at your line and you have enough strength to kill them all, you can advance your whole line one hex south, allowing you to get additional attacks on them from non-frontline troops. Once you advance a unit to the first water hex at west board edge, the west leader will probably come out to greet it, so be ready to fry him with Haldric's ruby. After killing the leader, back up into good terrain to prepare to meet the dragon.
** "Wake the Dragon" strategy: Prematurely wake the dragon (see spoiler below) and back up your troops to north of your keep. When the dragon comes, kill him. The scenario can be over on turn 7. There is no early finish bonus for this, but you can recruit lightly so that you still have gold at the end and will carry-over 40%, if you need it for your next scenario.
* With all these strategies, the Saurians may hold back for quite a while. This is okay, as the Dragon will eventually appear and come to you. Kill it. Then you are given a choice of whether to end the scenario or to try to kill all the enemy leaders before time runs out. You can choose to finish the remaining Saurians for a nice bonus. However, on the hardest difficulty setting the turn limit (33 turns) is insufficient for you to plow through the vast hordes of level 0 spam to get to the leaders, so it's best to simply end the scenario after killing the dragon.

Spoilers...
* The dragon will awake on turn 15 or when you move a unit down around the road north of the mountains. If you wish to wake the dragon prematurely, you can recruit a Horseman on turn 1 and run him down. It's a suicide mission for him, however.
* If you have a fast non-horse unit in position, rush it to the mountain cave after the Dragon leaves to grab the 200 in gold, though that's nothing compared to the Hero bonus for defeating all the Saurian leaders. So focus on killing all of them first.

====Lizard Beach====

This is a scenario versus Saurians, Giant Scorpions, and Mudcrawlers, where good recruiting and strategy will save you from massive bloodshed.

Recruiting...
* Mermen are helpful for the swamp and water areas.
* Bench some or all of your loyal Iron Maulers, veterans from ''The Fall.'' They are laughably ineffective against the impact resistant Mudcrawlers - and laughably vulnerable to their ranged attacks.
* Thieves, Horsemen, and their advancements are good for mud cleanup, though you must keep them out of range of Saurian skirmishers. Swordsmen and Royal Guards are also good, though overkill.
* Recall a lot of fairly high HP units, preferably with strong non-impact ranged and melee attacks.
* Mages are good. Mages of Light are especially useful, since they can do front line duty. Lots of healing may be necessary, about 3 healers are good, so White Mages can be used too. Raw recruit Mages can be used as well, for disposal of Giant Scorpions and the occasional Saurian Skirmisher that wanders too far. At least one Silver Mage is highly desirable, along with a speedy unit (e.g., Fugitive, Footpad, or Horseman) to capture villages for the Silver Mage to use north of the river.
* [fredbobsmith2] An alternative strategy that works surprisingly well is to simply use a very mage-heavy army. Recall most or all of your high-level mages, throw in a few peasants, and spend the rest of your gold on recruiting mages. Victory will come with shocking ease.

Strategy...
* General strategy: as Saurians have skirmishers and a lot of movement, be sure to protect your wounded units well. Because of the Saurians unnerving ability to concentrate their fire on one unit, be sure to keep several healers around and try to keep your line straight so only two can mob one guy. Hedgehog tactic also seems to work well.
* Opening strategy: here are some specific strategies that players have used with success in the early part of the scenario:
# "Mermen in center" strategy: Recall 2-4 Mermen, 1-2 Trappers/Huntsmen, and a lot of high HP troops, then form a line. Initially, you can either form a north-south line around the lake area with one flank at the south board edge, or, if you want to be conservative, you can do a diagonal line in the southeast corner, with both flanks tied to board edges. You'll need the Mermen to handle the lake area, and Trappers/Huntsmen/Mermen for the swamp areas. Keep troops in reserve, so that when a few Saurians meet your line, you can advance your whole line over them. Do not be too conservative/defensive on hard, as your time is limited.
# "Mermen on flank" strategy: Recall several decent land melee units & then 4-5 level 2 Mermen on rounds 2-3. Most of your force forms a line of battle near your keep, Mermen on the north flank in the river, land units extending south, flanks bent back with strongest units at the corners - then let the Saurians break on it. Once their first wave has broken, the rest of their troops come in drips and are no problem, so now you can split up and wipe out the stragglers and claim villages; any L2 units you start with should level up. After you defeat the main force from the south send just one or two guys north to capture towns so your Silver Mages can teleport into the fray.
# "Mermen feint" strategy: Recall most of your Mermen from before and send them along the river towards the sea. This will harry the saurian troops coming down from the north, allowing your main force to advance on the southern enemy undisturbed. Beware, though as your mermen will encounter the Saurians at night time (giving you -25% and them +25%), so try to minimize conflict until dawn, just get in their way.
# "No Mermen" strategy: On your first two turns recall two keeps of strong, fast veterans like mounted units (not Paladins though; they're pretty ineffective against saurians), Outlaws/Assassins, and Silver Magi along with some other veterans, preferably with a lot of HP: if all goes well (at least on easy and medium) that may be all you need. Dash them across the swamp directly west of your keep, south of the sands, and form a line with strong units at the ends. They'll flank you, but you're stronger than them and you can use your slower units to crush the flanking saurians in a hammer and anvil. The first wave of southern Saurians should get itself killed before the northern Saurians arrive in force. Once the northern Saurians arrive, take them out with your slower units while your quicker ones go for the southern leader.
# "Sacrificial lamb" strategy: In addition to a couple mages, 2 healers, and some other fighters, recruit a castle-full of peasants to draw the Saurians out onto open ground. Surround a single peasant on 5 sides, with 2 healers behind him. Build your formation around that.
* Closing strategy: The enemy's onslaught tapers out after their initial wave, so the final push for the southern leader should be quick and clean. Taking out the northern leader is harder, because all of your units will be stuck south of the marshes and the river. If you want to go for a quick win, just march forth with Silver Mages, Mermen, and anyone who's close enough to be a help. If you don't want to lose any of your better units, patience may be the key.

Spoilers...
* When one of your units gets as far west as the second bridge, a wave of Nagas will arrive out at sea. You may wish to delay going that far until the second watch, so that the Nagas will make contact with your forces during the day.
* Killing one leader gives more gold to the other, so when you've defeated pretty much all the southern leader's forces, just plant a level 3 or two in his keep and leave him alive; kill them both in the same turn.

====The Troll Hole====

This is a scenario that you cannot win by brute force, because the trolls have more brute force than you. Wise recruitment and strategy are necessary.

Recruitment...
* It's underground time again, so as before, mainly recruit mages. The trolls are strong, so hopefully you have lots of levelled up mages. Mages of Light are especially nice, because they are tough enough to survive an attack from most trolls, while simultaneously reducing the damage sustained (due to illumination blinding the trolls.) Level 1 Mages can be used to good effect too, especially if quick. If only attacked by a single Troll Whelp, a healthy level 1 Mage will survive.
* In addition to mages, your chaotic units can be helpful here again, especially against the occasional Rocklobber, which you will not want to attack with mages.
* Forget about your loyal Iron Maulers (leveled up Heavy Infantrymen from ''the Fall''). They are too slow. It's not that you'll be running around, but you will be rotating troops due to heavy damage, and they will only get in the way.
* Putting Mermen in the moat will really help you fend off the first wave of attacks.

Strategy...
* There are 4 castles, and two of them (randomly placed it seems) are the troll leaders you need to kill.
* Try to use the narrow corridors to your advantage, so the enemy can only place one attack against a strong unit of yours, but you can kill a troll at a time with two mages or Haldric. Also keep an eye at your back since they will try to surround you. And resist the temptation to send single units wandering around in what seems empty caves - they will all die, probably by the fangs of a Giant Spider.
* Try to arrange it so one troll can enter to be attacked by many troops. Have regular troops in front initially. Move mages forward to finish the troll, plug the gap where the troll was with Burin or a Royal Guard or an Iron Mauler, and reset the trap on the next turn. When you've whittled down the enemy, go the direction they came from and kill the leaders, ignoring spider keeps.
* Alternative: This could be a good choice if you have low gold: recall 2 quick red mages, and 3 quick tough melee units (say 2 royal guards & a L3 chaotic unit like a Fugitive). Play expedition style: abandon the start island, stay fairly close together, with your troops roughly divided in two between those moving forward and those fighting rearguard. Provided you knock out one troll leader early, the rest is manageable, just work your way carefully over to the other.

====Cursed Isle====

You will be fighting undead, mostly of the incorporeal and ghoulish lineages. Victory comes surprisingly easily.

Recruitment...
* Recruit lightly, certainly no more than two castles of troops. You could use 1-3 Paladins, 1-2 Mages, and 1-2 White Mages / Mages of Light.
* Recall your loyal Merman Triton or similar and have him pick up the holy water.

Strategy...
* This can be the first or last quest you choose. If you can wait, do it last, as you will come out of it with a lot of gold, which you will need for the first scenario after the quests, ''The Vanguard''.
* Keep a very tight formation for the first night, as Shadows will hit hard and you don't want to get backstabbed or swarmed. By dawn, it should be smooth sailing.
* If you get anywhere near the enemy leaders' keeps, expect to get rushed by a leader.

Spoiler...
* In one of the three temples there is a Vampire Lady. All you really need is a Paladin or three to rush the temples. Kill her. Game over, you win. One of the other temples has some gold; grab that first.

===A Spy In The Woods===

Plot only.

===The Vanguard===

You will be fighting a large number of orcs, trolls and other enemies in a location with a natural defensive line, where presumably an underground river has carved a line of sinkholes. This scenario will be difficult or impossible with minimum gold (200), but quite doable with a large amount of gold (450+) even on the hardest difficulty setting. Recruitment and strategy are fairly straightforward, given the board layout.

Recruitment...
* Recruit a lot of units; you will need them.
# First turn, recall/recruit speedy units: Knights, Lancers, Paladins, Horsemen, Outlaws, and similar.
# Second turn, recall your loyal Iron Maulers (leveled up from ''The Fall'') and Spearmen/Swordsmen/Royal Guards.
# On subsequent turns, recall/recruit healers and other sorts of Mages, Thugs and their advancements, and Longbowmen. You will need quite a lot of healing power: 3-4 White Mages / Mages of Light and 1-2 Paladins. A Silver Mage would come in handy, since your forces will be widely spaced, but you could start with a couple of Red Mages and try to level up one or both to Silver Mage.

Strategy...
# This map is smaller than fog of war and sinkholes make it appear. Rush the west and northwest gaps with mounted units, but slow & strong will carry the day once the sun rises and the odds are in your favor.
# Seal of all the gaps in the ring of sinkholes. When the onslaught begins, wounded units can retreat back into villages or be cared for by healers - or actually both, since soon you will be out of non-wounded units.
# A "Sitzkrieg" may develop, where neither side can make progress. Shift units to the southwest and break out there, using the west board edge defensively. From there, sweep northwards, taking out the western orc leader first and then the next orc leader.
# Don't forget the chest of gold, which you can see even in fog.
# End the scenario with the kill of the final leader, a level 3 troll.

Spoilers...
* Once you kill more than half the units of any side, a few tough undead units will appear near that side's stronghold at the edge of the map. So, this will happen three times. Beware the Chocobones. Their double damage from charge means they can take out Commander Aethyr at night just by hitting 2 for 2, and they will certainly try if they get the opportunity.
* Heads up: the next scenario is much less difficult with extra gold. You can use Peasants to avoid going negative on gold, promoting them to Spearmen only when needed.

===Return of the Fleet===

Welcome to the "kitchen sink" defense. You've made it this far; now the enemy will launch a desperate defense, throwing a little bit of everything at you. The effect is mostly psychological, but it could be a problem if you came into the scenario with minimum gold or your initial assessment causes you to drastically under-recruit. Time is money.

Recruitment...
* On medium, at least, you don't want to overrecruit. First turn, recall Mermen to assassinate the undead leader; 2 Entanglers/Netcasters and the Triton with the Storm Trident. Later, you should recruit 1 or more Silver Mages also for this taskforce as well as for causing general mayhem. It's also worth recruiting 5-10 L1/L0 units to take the brunt of the first wave of attacks; you can use any combination of Footpads, Poachers, Thugs, Spearmen, and Peasants, as you see fit. You'll want some decent L2 and L3 recalls for healing, to flank your lines, and to start kicking some butt at daybreak. A Mage or Red Mage to blast Trolls and Chocobones will level up by end of scenario. Paladins are good too. In addition to your loyal Mage of Light, you will need a bare minimum of 1 more healer.
* On medium, don't recruit too much for fighting the undead - 2 Paladins at most, 1 or 2 Thugs, the stormy Merman, and the nearest Mage working with your land force are sufficient - the undead commander only gets 5-6 L2 recruits and they come ashore scattered (on medium, anyway). Paladins are so effective against undead that you can wade into the water after them. Just remember, Paladins can't go into deep water and undead can.
* On hard, you also don't want to recruit too much for fighting the undead, but it's only because going on an offensive early against them will get you crushed by a Chocobone armada.

Strategy...
# Move the Mermen (including the storm trident) as quickly as possible pretty much straight to the West. (There is a village and swamp hex that can aid your travel if you pick the best route). Move these guys up the West side once they get there to get to the Undead Leader as quickly as possible.
# Your loyal units can do a little village grabbing, but it would be unwise to venture too far north.
# After nightfall, fog will appear; for the rest of the scenario, the map will become shrouded, like in a cave scenario. So while you're still amazingly able to see, note the key terrain features, castle and city locations, and troop dispositions (especially Chocobones.) Also, visually explore the avenues of approach you want to be able to see later.
# The first wave is largely at night and will have Goblin Knights and Pillagers, and later Chocobones and Troll Warriors. The damage they can cause is bone chilling, so make sure to divert their attention with plenty of spam. You want to meet them on the edge of the woodland, while inducing the orcs to fight from the grassland. Footpads and Poachers are handy here, as they have high defense in woodland. Players have had success setting up the initial line in either the north and northeast woodlands, with respect to the castle. Others have succeeded by fighting mostly from the open plain, retaining mobility by leaving the woodlands to their Footpads.
# Once your Mermen have taken an island city, teleport over one or more Silver Mages to help kill the undead leader - in addition to a Silver Mage, you will want the storm trident, a Netcaster/Entangler, plus one more leveled unit to be fairly sure to knock him out in one round. Quick striking like this you end up fighting a lot less undead. You probably end up foddering one of the mermen to the Undead Archers, but the trade off is well worth it. You can keep cycling your mermen up to fight with any orcs or trolls that come into the water. Silver Mages can assist, since they are not needed much in the other part of the fight.
# After the undead leader is assassinated and the first wave is broken, you may advance cautiously due north or to the northwest along the coast and ultimately finish off the two orc leaders.

Spoilers...
* When you are close to the break in the woods at the east board edge, tighten your formation and keep wounded units well away, as a small force of high-level Saurians will appear. Trigger them in daylight if possible, and knock them out fast. Alternatively, you can delay triggering the Saurians as long as possible by moving your force northwest near the water and then onto the small island, though even then it is possible to trigger the Saurians if you are not careful where you step. (Stepping to 10 hexes or less from 34,15 triggers the Saurians.) You can fight the final wave of orcs from the island, then move northeast to the mainland, finally triggering the Saurians.
* Two cuttlefish appear when you approach the north-central island. Assuming you're sending a strike force through the water to knock out the undead commander, you really don't want to trigger these until that force is on the island - the storm trident Merman is the only thing that can stand up to them in water, and they will avoid him to attack more vulnerable units.
* Once you kill one enemy leader, the other gets more gold & recruits a new wave of L2s. This can be useful if you need to kill off surplus L1 units to improve the finish bonus, or if you need the XP more than the gold; otherwise, try to knock out both leaders on the same turn before they can recruit more. Alternatively, if you kill the first one at dawn, the second will be reluctant to attack with his L2s in daylight, and you might jump in and kill him before he uses them.
* Heads up: The next scenario is the final one. Therefore, loyal units are now somewhat disposable. However, you will need plenty of gold. Recruit some Peasants in the current scenario if you need to save some gold. Not only are they cheap, but they have no upkeep and Chocobones love 'em. Send a unit with leadership with them and they can even deal some amount of damage and be used to finish off wounded enemy, though at night you should just let them take the beating passively since otherwise they die too quickly.

===Rise of Wesnoth===

It's the final battle: be patient, recall everybody - the early finish bonus doesn't mean anything. Also, loyal units are no better than other units after your recruitment is finished.

Recruitment...
* You will need at least 300 starting gold, maybe more like 400 on the hardest difficulty level, so if need be, replay the previous scenario.
* To stretch your money, start with loyal Iron Maulers and a couple ready-to-level level 1's and level 2's. Finally, recall as many level 3's as possible.
* Healers: 3-6 Mages of Light / White Mages. Your few chaotic units will appreciate a White Mage.
* Horse units: 2-4 Paladins, 3-4 Knights / Grand Knights.
* Horse escorts: about 3 speedy units, like Royal Guards, Fugitives, and Silver Mages.
* Tanks: at least 6 high HP units, such as Royal Guards, Highwayman, Master Bowmen, and the loyal Iron Maulers.
* Mages: at least 3 high level Mages aside from your basic healers, so Arch Mages, Great Mages, and Silver Mages. Additional Mages of Light can be substituted.
* Some Mermen might be useful here, but surprisingly, they're not really necessary.
* On 1.9.3 and earlier, you can recruit Saurian Skirmishers on medium and Skirmishers plus Ambushers on hard. This appears to be a bug, so ignore the option.

Strategy...
* You will launch a two pronged assault: mounted units will race to the west and then south, while the main army heads due south.
* With your mounted units, race forwards by day and backwards by night.
* Along with the mounted units should go some escorts, speedy foot units intended to kill things like Goblin Impalers, which make even Grand Knights nervous. They would also benefit from a quick Mage of Light.
* Meanwhile, with your tanks and the rest of your healers and support units, form a line or hedgehog in the woods just south of your keep or next to the river.
* Keep your leaders with the main army, to avoid drawing too much attention to the mounted detachment.
* Maintain awareness of the overall battlefield. If the main army gets in trouble, you can send some or all of the mounted units to assist. There may be an opportunity to hammer-and-anvil enemy forces trapped in the middle. And you may wish to transfer units, like Paladins may be useful to the main army after it is on the move.
* You'll need at least two Paladins to kill Jevyan himself; nothing else is half as effective (except perhaps Mages of Light and suicidal Lancers). Or you can use a pair of Great Mages (unless you are very unlucky, you should be able to kill him in a single turn). Don't forget to sacrifice Aethyr to Jevyan. If he doesn't want to come out and play, march up to Jevyan and use a crossbow attack. When Jevyan is dead, the yellow and green leaders may still be alive. You'll have to kill one, leaving at least one orc leader alive. You pick. Congratulations! Enjoy the ending!

Spoilers...
* When one of your units is within 8 hexes of a bridge, but you have no units within 2 hexes of the bridge, and there are no units on the bridge, then a Cuttle Fish will appear and destroy the bridge. This is usually disadvantageous. Not only does it leave you with a Cuttle Fish to fight, but it slows your progress south and the bad guys progress north. At least on the hardest difficulty level, it's hard to kill all the spam in time, so you don't want to impede their advance by removing the bridge.
* When any of your units is killed, it becomes a Walking Corpse. On hard, it becomes a Soulless, which makes it important to be careful with your level 2's, especially Lancers.
* After the first orc leader is killed, then some gold goes to mister Lich. It's 40, 80, or 120 gold, for easy, medium, and hard, respectively. The lich will receive some gold once you kill his Familiar.

== See Also ==

* [[MainlineCampaigns]]

[[Category:Campaigns - The Rise of Wesnoth]]
[[Category:Campaigns - Walkthroughs]]

TheRiseOfWesnoth

2013-06-17T20:06:00Z

Anonymissimus: /* A Harrowing Escape */

== Strategy Guide for The Rise of Wesnoth Campaign ==

===Campaign strategy===

Over the course of this campaign, you will need to level up to some:

* Healers: White Mages/Mages of Light (at least four)
* Undead killers: Paladins (two)
* Mobile strikers: Silver Mages (at least one, preferably more), Grand Knights (several), Fugitives (one or more helps)
* Damage sinks: Royal Guards, Iron Maulers, Highwaymen, Halberdiers, level 3 Burin, and again Grand Knights
* Leaders: level 3 Haldric, level 3 Lady Outlaw, and much later level 3 Commander Aethyr
* Ranged attackers: Great Mages (can use several in the last scenario), Longbowmen/Master Bowmen (two), Trapper/Huntsman (one is helpful)

A Mage of Light, one Paladin, and five Grand Knights make a perfect assault team!

Although Horsemen are key for the first three or four scenarios, it's important not to be too reliant on horse units through the middle part of the campaign, as there are many hard levels underground, in swamps, in water, or against Saurians; use XP from the scenario ''The Vanguard'' to get to 2 Paladins and 2+ Grand Knights.

Don't overlook Pikemen/Halberdiers, which are useful in many levels; pierce attacks work well against Drakes and against the dragon, and they are handy for defensive roles especially repelling Wolf Riders. They are less good against undead, though, and don't get that +1 MP Royal Guard speed bonus.

Due to many undead opponents, you will want to recruit many Thugs at times, and get a few (the quick ones, since you need them underground) leveled up. Footpads help too, once leveled up. Due to swamps, you will sometimes be spamming Poachers, which get marksmanship once at level 3. These, plus Lady Outlaw, give tactical options at other levels too: some decent chaotic troops form an ideal reserve, since you can attack with your lawful troops at dawn, and by nightfall when you need to heal them, use some chaotic troops to either continue the attack or to shield your healing lawful units.

Here are some recommended units to have obtained by specific scenarios:

2. The Fall - 1 Knight 
3. A Harrowing Escape - 1 White Mage, 2 Knights, plus about-to-level troops 
4a. The Midlands - avoid, go to The Swamp of Eden instead 
4b. The Swamp of Eden - level 2 Haldric, level 2 Lady Outlaw, 2 Knights, 2 Shocktroopers 
6. Temple of the Deep - level 3 Haldric, level 3 Burin, 1-2 Mages of Light or several Outlaws / quick Bandits 
8. Clearwater Port - level 3 Lady Outlaw, 3 White Mages / Mages of Light, 3 Iron Maulers / Royal Guards / Halberdiers 
12. A Final Spring - 1-2 Silver Mages 
14. Rough Landing - the 3 loyal Mermen from the previous scenario, ''Peoples in Decline''[glandis] In 1.8.6, there was no opportunity for 3 loyal mermen - maybe this was in an older version? And only Merman fighters can be recruited - no Netcaster upgardes are possible 
17a. The Dragon - up to 4 White Mages / Mages of Light 
17d. Cursed Island - 1 Paladin 
19. The Vanguard - 4 Knights/Lancers/Grand Knights, 2 Paladins (or about-to-level Knights) 
20. Return of the Fleet - 1 Mermen Entangler, 1 Merman Triton with Storm Trident, level 3 Commander Aethyr desirable 
22. The Rise of Wesnoth - 2 Paladins, 3 Royal Guards, 4 Mages of Light

Because the campaign is long and you won't be able to recall all your level 3's in the final scenario, it pays to create some "uber-units". An example is a quick, resilient Silver Mage that has been AMLA advanced a few times.

==Scenarios==
===A Summer Of Storms ===

This is a relatively easy scenario, so gear your recruitment and strategy with an eye towards gathering XP.

Recruitment...
# For the first round, recruit 2-3 Horsemen and the rest can be all Spearmen or a mix of Spearmen and Bowmen as you see fit.
# Then, you should probably hire Bowmen and more Spearmen. Whatever Bowmen you can get advanced will be useful later on for fighting the many trolls, grunts, and riders you will encounter. Note, however, that you will not have any healers until you level up at least one mage to White Mage status, and the sooner you can do that the better. Red mages will also prove very useful in subsequent scenarios, so consider recruiting at least two mages.

Strategy...
* Players have used at least three strategies with success...
# The "over the bridge" strategy: Send the horsemen with the king over the bridge, and the others should follow or start going over the mountain, to avoid being attacked from behind. Send subsequent Spearmen and Bowmen on the "over-the-bridge" road, and when the Prince and final troops have just about caught up, march on the enemy camp.
# The "hide in the swamp" strategy: Proceed much like the above, but send the king with 3 Horsemen to capture the nearest houses, then retreat into the swamp area until you have your lawful bonus to kill off troops during the day. To hold them back, you can use a Spearman and a Mage (to level him.)
# "Sandbagging" strategy: On the hardest difficulty level, the initial enemy assault will only be easy to handle by entrenching your troops behind the river. Use the king to block the bridge initially, while Spearmen handle the shoreline just north and Horsemen carefully flag villages across the river. Run the king around, lending his leadership as you massacre the stupid enemy troops that have jumped like lemmings into the water.
* For all these options, you will also need to send a squad north into the mountains and around into the flank of the enemy. A quick Spearman, a quick Bowman, and one other unit, possibly a quick Mage, should be more than sufficient.
* When you see that the fronts are under control, stop recruiting and send prince Haldric and your Mages over the bridge on a quest for XP, assisted by the leadership of the king, and converge on the enemy camp.

===The Fall===

This is a scenario that looks scary, but it is only moderately difficult with proper recruitment and strategy.

Recruitment...
* Recall or recruit Spearmen and Bowmen to man the lines.
* Horsemen/Knights are desirable, because you probably do not yet have a White Mage, and the villages are widely spaced.
* Recalling or recruiting Mages for XP gathering is highly advisable for future scenarios.

Strategy...
* There are three basic approaches to take out the outlaw leader...
# "Brute force" strategy: You can march west with a large army and use part of it to hold northwestern orc. Use the rest to fight outlaws and kill the leader. This strategy requires a lot of troops but it can bring you plenty of experience and can bring a quick victory.
# "Assassination over the bridge" strategy: You can assassinate the outlaw leader. One way is to wait until the orcs have killed almost all outlaws and then assassinate the outlaw leader with Knights, rushing over the enemy camp's bridge and into the keep. This strategy is risky because orcs can kill the leader before you.
# "Assassination via the mountain pass" strategy: Another way to assassinate the leader is to send a squad through the southern mountains to the outlaw keep. Two Mages and three Spearmen are enough. You may wish to substitute one of the Spearmen with a Knight or Horseman, though horse units have only a narrow passage devoid of mountains and could get pinned by the enemy.
* On the hardest difficulty level, you may be forced to assassinate. For either of the assassination strategies, it is a good idea to fight against the northeastern orc nearby your keep. This way, you can secure your back and earn experience.

Hints...

* Saving the loyal Heavy Infantrymen (or Shock Troopers on easy) pays off in later scenarios. To save all three, move them south towards the outlaws.

* Once you eliminate the HP of the Lady Outlaw, she offers to help you. If you say yes, she comes back as a loyal unit in future scenarios and you will be able to recruit outlaw units, plus she cannot be killed in the next couple of scenarios (instead, she disappears when she goes to zero HP, and comes back the next scenario.) This is quite valuable. If you say no and try to kill her, you find out she cannot be killed. However, you do get 200 gold that she leaves behind.

* Heads up: The following scenario (''A Harrowing Escape'') is a handful on the hardest difficulty level. On hard, a carryover of almost 150 gold (so you have 250 starting gold) would be wise, so although Lady Outlaw's assistance is worth much more than 200 gold, you may be forced to choose the gold. Another thing you need to beat the following scenario on hard is a White Mage at or near the start of the scenario. Also, about-to-level units will be especially nice for their self-healing ability and low initial upkeep. Steer XP accordingly.

===A Harrowing Escape===

This scenario is much easier on lower difficulty levels, calling for different strategies.

On easy/medium...
* Recruitment: You should recruit/recall at least one, possibly two Mages here, and use them for killing Goblin Spearmen and finishing off injured Wolf Riders in the hills & mountains bordering the valley. Other than the Mages, simply recruit what you want, and go along the road. You get enough villages to pay upkeep for quite some army, and can give some of them a bit of experience.
* Strategy: Leave a few units in the rear, as the enemy can cross hills quickly. Note that Footpads and Outlaws will also cross hills at reasonable speed, if you need to hunt down some units. There are two castle tiles about halfway down, try to send Lady Outlaw and Brunin the Lost to them, they make good guards in case the enemy tries to come straight up. You can also send a couple groups of units down southeast to the lake, so you can prevent the Green team (southeast) from coming up the river. You can also kill the two Orcish Grunts (or Warriors on medium) on the southern castle tiles and then move Lady Outlaw and Brunin to them.

On hard...
* Recruitment: To beat this scenario on the hardest difficulty level, you need some level 2 (or better yet, about-to-level level 1) units already and a lot of starting gold. It is possible with ~200 starting gold, but only barely. 250+ is better. You can stretch your gold a bit by not going negative on upkeep and waiting until you can't wait any longer to do one last round of recruiting, recalling mostly level 2's. For timing your final recruitment, watch the wolves that are likely trying to flank through the mountains south of your keep. Another requirement for beating this scenario is a White Mage (or two.) If need be, you must promote a Mage (or two) tout de suite, as you will be dealing with severe damage and assassins, while only having easy access to 2 or 3 villages initially. Horsemen and Knights are useful for dissipating damage by serving as meat shields against blades and then running off to remote villages to heal. Quick Horsemen are especially nice, as they can transfer between two strategically placed villages in one turn, for healing on the go. Horsemen, Knights, and Swordsmen are useful for swatting assassins.

* Strategy: More important than terrain is avoiding getting flanked, so mobility of individual units is key; if you climb up deep into the mountains, you will have a harder time with mobility than staying on or near the valley floor. Additionally, many of your units cannot go on mountain hexes, so it's easier to maintain your lines if everyone stays close to the valley. Near the start of combat, it's crucial to kill units quickly on the road: first the wave of wolves, then the wave of assassins. In contrast to easy and medium, on the hardest difficulty level both pairs of roadside castle tiles are guarded, not just the second pair. As on medium, the guards are Orcish Warriors.

Hints...
* On medium/hard, you can lure out the roadside guard Warriors one at a time by putting a unit within attack range of one (and out of range of the other.) They mostly come at night. Mostly. That is, the Warriors might not bite bait put out during the day.

* If you have Lady Outlaw, note that she has leadership, which will be useful to help promote Prince Haldric, if he is still level 0. It's worth advancing her to level 2, to continue to provide leadership to level 1 Haldric and your other level 1's. You may also make use of her odd ability "distract", which allows adjacent allied units to ignore ZOCs. And Lady Outlaw allows you to recruit outlaw types. On hard especially, Thugs can be useful as meat shields and to provide strong attacks at night when your lawful forces are crippled. Remember too that Lady Outlaw cannot be permanently killed (at least not yet), so when desperate times call for desperate measures, you can move her into a suicidal position.

Spoilers...

* The scenario can be beaten with 154 gold only (I decided to trust the lady). Key points in the strategy I used:
** Underrecruited as heavily as possible, so that the upkeep of my current units is completely offset by my villages. Only 2 footpads to go for Burin and villages down the path right at the start. Only level 2 unit I recalled initially was a white mage. Recalled the 3 loyal HI and tried to arrange it so that they aren't attacked by archers. Recruited several thieves, since they are cheap and the grunts are font of attacking them instead of my mages (and they still often survive on 70% def).
** During the main phase of the battle, stayed on the safe side of the river (this was the actual key point). Used the river, mountains, castle and swamp to have good defense for myself and bad one for the orcs. As shortly as possible before my income turned negative, recruited/recalled an additional 5 units. Needed to give up the village abroad the river as well (so only 3 villages left).
** What also helps as well is the fact that there are two enemy sides as opposed to a twice as strong single enemy side. If one of your units could be attacked by 3 enemies, but 1 of these hexes is currently blocked by the other side, the currently moving enemy decides to attack units which it (they) is (are) actually less likely to kill than that one. AIs don't cooperate, that is.

* There is Dwarf Steelclad in the village at 8,5. It's not far from your camp, so send Lady Outlaw there. Dwarf joins you because "It has been a long time since he felt the satisfying crunch of Orcs under his Axe."

* After you kill the first orc leader, an Orcish Slayer and two Assassins will pop out of nowhere, so you would be wise not to have any wounded units stuck without movement points at that point. Also, the other leader will get an infusion of gold and start recruiting on all available hexes, so if you can sit on some of those hexes first, it will help keep the situation from getting out of control.

* At the end, you will be given the choice of the river/swamp road or the midlands/orc road. These fork to the scenarios ''The Swamp of Esten'' and ''The Midlands'', respectively. The swamp scenario is relatively easy, while ''The Midlands'' could cost you some leveled units or even prove impossible to beat if you are low on gold. Also, the swamp gives you a free loyal White Mage, so it's a no brainer, unless you want more of a challenge.

* Heads up: it would be wise to have at least 1 Mage either levelled up to White or about to level up before going to the scenario ''The Swamp of Esten''.

===Diverging Campaign Path===
====The Midlands====

Orcs again. But you chose that way. This scenario may appear impossible, but with a lot of gold and a little strategy, it can be beat.

Recruitment...
* You are given plenty of time, so use it wisely. The enemies send lots of orcs, mostly weak ones. So recruit and recall everything you can.
* Recall any White Mages you have. You'll need them.
* Bowmen are good for the wolf units you will be facing.
* The rest depends on your strategy.

Strategy...
* The "Fast Assault" option: use an assassination team. If you go west, only your Knights and Horsemen will arrive and fight at daytime. So go south. Take the bridge and defend against the enemy closing in from the west. Take out Yellow with a fast assault team (they should take a healer along), but be careful about the leader. Your main force moves west, takes and holds the second bridge, and takes out Blue. Your assault team stays in the south and goes for the last enemy leader - they won't face any serious resistance. The enemy moves north to support Blue. The HI guarding the bridge might gain a level or die, but hopefully not the latter, as they are loyal units in a long campaign. With this approach, you can finish early (around 25 turns) and keep your losses low.
* The "Dark Assault" option: use Footpads. If you chose to work with the the outlaws in the last round, then this works well. Footpads are cheap. And they are fast. And they have good defensive abilities. Plus they fight well in the dark and in the forest. So recruit lots of Footpads-pawns and quickly dispatch them to the upper west and south, followed by more powerful units: Mages, Horsemen, etc. For the time being, leave the middle enemy alone. To the upper west, send several Footpads into the forest and capture the village and set up a defensive line. This cuts down the enemy's gold and increases yours. Don't attack at first, just defend, until more of your slow higher powered units arrive. The strategy here is to pick off the orcs, and send the Horsemen to capture villages. While this is going, to the south you send your Footpads to capture any villages you can and, more importantly, put a Footpad on the hex that is adjacent to the bridge, thereby stopping easy advancement of their greater numbered troops. A White Mage, a couple Trappers and some Bowmen would make a good escort. Probably sending a Thief or two would be good too, to help dispatch any enemy that infiltrate the villages north of the river. one enemy got into one of the villages on the north of river, and it took a lot to dislodge him. The intention is to engage the enemy so that they are fighting from the river squares, at a huge disadvantage.

====The Swamp Of Esten====

This scenario is not too hard if you are conservative and don't send important units off alone.

Recruitment...
# First round, recall 1-2 quick Knights (or Paladins, if you have them), recruit 1-2 Horsemen, and recall your loyal Shocktroopers or whatever they are now.
# Next round, recruit/recall Mages to kill Scorpions (and Bats) and at least one White Mage to deal with poison, plus maybe a Poacher, as they are good in swamp (and you would like a Huntsman eventually, for its markmanship.)
# A little Thug spam can come next, but you don't need a full third round of recruitment. Then send Prince Haldric off to lend his leadership.

Strategy...
# You must blitz the northeastern leader, or risk getting bogged down on bad terrain facing a swarm of undead spam, which can be nasty at night. Quickly send Knights (or Paladins) and Burin over the ford to start wailing on undead. A disposable Horseman can try to take out Scorpions in this area at first. On the way is your proper Scorpion disposal unit, the Mages and White Mage. Try to kill Dark Adepts with Burin or horse units before they have chance to attack you. As you close in on the leader, hover your mouse over him to watch where he can go, as his ranged attack is nasty and can be followed up by waves of kamikaze Walking Corpses, which can take out a Knight.
# After you have killed the northeastern leader and eliminated troops there, you can either send your whole army back across the ford and south or split your army into two halves, sending one part to each leader. If you have lost several units but have lots of turns left, it's probably safer to stick together. This is not a simple mop-up operation, as powerful undead can take out some of your valuable units if you're not careful. On hard, Shadows are a constant threat at night.

Spoiler...

* Searching the temples is a good idea. Some have gold. There is a free loyal White Mage hiding in (a random) one of the temples - visit the temple close to the keep ASAP, and if not there, try rushing a horse unit or Lady Outlaw to the temple at 19,5. However, some of the temples contain undead, so keep extra troops nearby when you enter one.

===The Oldwood===

This is a relatively easy scenario.

Recruitment...
# First round, recall your (probably leveled up) Heavy Infantry from The Fall and some quick fighters.
# Second round, recall White Mages and quick Mages.
# Third round, round out with Thugs, Bowmen, and Spearmen, preferably quick.

Strategy...
* Your forces will have three main combat arenas: the northeast, the south, and the middle.
# The main bulk of your force, including at least one White Mage, should head east to the orc in the northeastern castle. The leader there recruits a lot of units, and most of them are level 2, so watch out.
# Haldric, a White Mage, your loyal Heavy Infantry types, and a couple of level 1's (maybe a Mage and a Thug) should head south to the other orc leader. A few effective melee units can easily counter the riders they send early on, and then with a little forethought and patience you can take out their Archers and Crossbowmen without giving them time to shoot.
# The castle in the middle is inhabited by the tree folk, so don't bother sending troops there; however, you might want to keep a couple speedy units not far off to watch their backs, in case the allied leader gets into trouble, as is usually the case.

Spoilers...
* The temple contains the entrance to the catacombs, but you need the leader Wose's help to open it, and to get that help you have to win the current scenario, so there is no point in visiting this temple.

* Heads up: The next scenario is in the catacombs, i.e., underground, and it's a tough one, so you need to groom your roster accordingly. Two Mages of Light would make it a whole lot easier. Failing that, level up your fearless loyal Shocktrooper and chaotic outlaw types. Bandits/Highwaymen and Fugitives are especially nice. Quick units of almost any type (except horse units) will be helpful, if leveled and possessing high HP (>50).

===Temple in the Deep===

You will be facing undead underground. This is a difficult situation that will prove much easier with proper recruitment. Then the strategy will be fairly straightforward.

Recruitment...

* All in all, what you need is a small elite force. Two rounds of recalls is enough, if you didn't lose Burin in a prior scenario.
# First round, recall your loyal Shocktroopers / Iron Maulers, especially the fearless one, though their slow movement will prove frustrating. Also on the first round, recall a fast "tank" and someone to grab the holy water (if Burin is not your choice.)
# Second round, recall any Mages of Light you might already have, and a total of at least two White Mages or Mages of Light, preferably quick. For the rest of your recruitment, what you need are high movement (6+ MP) non-horse units with high hitpoints (>50 HP), preferably chaotic, preferably with a ranged attack, and preferably impact attacks. Put all the requirements together and it points to Fugitives. Outlaws and quick Arch Mages are worth recalling too. Fill out the rest with Bandits/Highwaymen, Trappers/Huntsmen, and Longbowmen/Master Bowmen, preferably quick. You might think that Red Mages would be good, but they attract melee attacks that they likely will not survive. Note that Horse units are too sluggish to be useful here and should not be recalled/recruited.
# Third round (optional), you can add a unit or two for a safety margin.

Strategy...

# There are two ways north, but they will meet up together before you meet any enemies besides the Tentacles. Ignore the tentacles for the most part and only kill them when it's convenient, as you will need to have a strong line set up by the time you engage the undead. Watch out for the enemy's Bone Shooters, Revenants and Deathblades, as they could easily mess up a level 3 unit. Once you see the two choke points, hold them so one of their units is facing 2 of yours (preferably with a White Mage behind them). You may be able to level up a White Mage to a Mage of Light while fighting in the choke point. If your troops are too slow to grab both choke points, you can send Burin and others to the west choke point while your slow troops line up at the southeast shoreline and bridge.
# Gradually progress northwards once the flow of baddies has tapered off, and once you get into the final chamber, the boss should be a piece of cake, although his ranged attack is devastating, so try to attack him with melee units. Be careful if he has recruits around, as their combined damage can take down one of your level 3's. Note that the Ruby can only be picked up by Haldric.

Hints...

* Holy water: Burin is very effective if you give him the holy water; however, it's more helpful to send Burin running to the west choke point without delay. A good alternative is a Highwayman - or a Bandit, who should level quickly. Compared to a Highwayman/Bandit, Prince Haldric or a Royal Guard is not that great a choice for the holy water due to their lawful alignment and -25% penalty, unless you have (or will soon get) a Mage of Light.

* XP: Use this level to get experience. The early-finish bonus is tiny. The tentacles are perfect for leveling up units. If you're hurting for leveled chaotic units, you can even level up two raw recruit Thugs (use Haldric's leadership to assist). Keep Burin away from the water at this stage, or he'll kill all tentacles as they attack, depriving those who could benefit from the XP.

Spoilers...

* Your killed units will be turned into Walking Corpses (or Soulless on hard.) Therefore, spam is not helpful. A Mage or two can be okay, if used with great care, but mostly you need to recall leveled troops here.

===Return to Oldwood===

Plot only.

===Clearwater Port===

This scenario is easy if you take the first boat out, more and more challenging for the second and third boats, and very difficult (on hard) if you want to take out all three leaders.

Recruitment...
# First turn, recall your loyal Shocktroopers / Iron Maulers from ''The Fall.'' You will also want several Footpads, for speedy village snatching, coastline defending (under leader supervision), and possibly for filling castle hexes if your lines get too thin.
# Second turn, recruit/recall more low maintenance units. It's a good scenario for leveling troops, so recalling acouple half-leveled Spearmen or similar is a good idea.
# Third and later turns, start recalling your high maintenance units. The key to winning this scenario is to recall several advanced units that can take a lot of damage and get good defense in castles (no Horsemen). You will also want at least 3 White Mages or Mages of Light.

Strategy...
# Backstab your ally, stealing all his villages. Your ally is useless anyway, except for the entertainment value from his troops' suicide runs. The income is much better in your hands.
# Send your heavy duty troops with some White Mages over to the line of castle near Lt. Aethyr. (Optionally, you can rush forward past the castle, but you will need to return almost as quickly before the main enemy wave and night arrive.) Aethyr will usually be done recruiting by the second or third turn, before the enemy reaches you, so fill the entire line with your units, and put Knight Sir Rudry in the one non castled tile (or leave it empty, if no enemy are adjacent.) Place the White Mages behind this line. After the enemy has reached you and it is your turn to attack, go mostly for the assasins, as they have a weak melee attack and their poison can be a huge problem.
# Meanwhile, on the northeastern coast, the northern enemy leader will send lots of units to catch your flank unguarded. Send 2 Footpads, a Spearman, Lady Jessene, and Haldric to guard the coast. If Lady Jessene is already level 3, you can substitute a Royal Guard, Swordsman, or Javelineer for Haldric. This coastline defense squad may need help later, so be ready to divert a speedy powerful unit there. If you keep a healthy unit on the village at the tip of the land, then, unless you are very unlucky, you will be able to hold off everything the northern leader sends. After the assault from the water has been crushed, some of your troops may be able to cross the ford north, but be careful not to get attacked in the water with only 20% defense. (Certain of your chaotic units do have 40% defense in water; now is a good time to pay attention to that.) Also, notice that the lighthouse has a similar effect as a Mage of Light.
# You have two options for the endgame:
## "Total victory" strategy: Once you've thinned the enemy to where they only have a few units that are close to your line, usually this happens conveniently around dawn, move your people out and start heading for their leaders. Split your force, sending a few down the southern path, to distract the eney and most of them toward the middle leader, to kill him. Once he's dead, send some of your army down to kill the southern leader and devote a few units to defending the bridge until the rest of your army can rejoin you. A unit or two with a lot of HP with a white mage are usually enough to do this.
## "Run like hell" strategy: Alternatively, you can leave your leader near the docks and take one of the boats to end the scenario.

===Fallen Lich Point===

This is a high variance scenario. It may be very easy or very hard, depending on events beyond your control.

Recruitment...
* Recruit fairly lightly initially, as you will likely have a chance to use the Lich's keep to recruit again.
* Mages, White Mages, and Mages of Light are good, and as are all the other advancements of Mages.
* You automatically should have your loyal Knight. Because of the mountains around "lichland" and frozen ground everywhere else, additional horse units are not recommended, except a single Paladin will come in handy.
* Some Thugs or a Bandit or Highwayman will provide a little extra undead bashing power.
* Footpads will help with village flagging, after the Wolf Rider types are taken care of, but you can postpone buying Footpads until after killing the Lich.

Strategy...
# The Orcs will be busy with the Yetis, so you can walk with a big group south and kill the Lich-Lord. Move Haldric to the stone monument to de-petrify the Lich. It may help to post some units around the undead before doing so. Use several mages to make a hole or two in the ring of undead, and then push in a burly fighter or two and/or Paladin to kill the Lich.
# After killing the Lich, assess the Orc/Yeti situation (as well as the empty village situation) and decide if you need to use the Lich's keep to recruit some reinforcements.
# After that, head north and walk into the sewer entrance (the "cave") or else kill the orc leaders.

Hints...
* It is also possible, if you recruit heavily, to split your force and head north to attack the eastern Orcs before they finish with the Yetis. However, be careful not to be attacked by a Yeti yourself; a Yeti is dangerous even if heavily wounded. A Yeti will attack you if it can get to a unit within one turn (and it doesn't have a more appealing orc target.)
* When dealing with the Lich, be aware that he has money; if you let him vacate any of his encampment tiles, or if you kill any of his units but do not occupy their tiles, he will be able to recruit. (This is not necessarily all bad, as it can mean more experience, but depending on the strength of your force you may want to be careful.)
* Note that this level becomes a lot tougher if the Yetis get poisoned early on and quickly die. If this happens you basically have no other choice than to kill the orc leaders first.

===Sewer of Southbay===

This is a swampy underground scenario, but with attention to recruitment, it's not very difficult.

Recruitment...
* As always underground, you want non-horse units with 6+ MP.
* Recall White Mages / Mages of Light, at least two, three is probably the optimal number.
* There are quite a few villages in this cave, so an expensive force is supportable, though not necessary. Some players recruit a large and spammy force, while others go with small and elite:
** Option 1, "Large and spammy" recruitment: Recruit four each of Mages, Thugs, and Poachers. Yes, Poachers normally stink, but here they really shine in a swamp that is permanently dark, underground. If you recruit four Poachers, you could finish with three Trappers and a Huntsman - or you could finish with four dead Poachers. The Thugs are especially likely to die, as they will be facing off against Red Mages, but somebody has to do it.
** Option 2, "Small and elite" recruitment: Recall something like one Red Mage, one Arch Mage, one Silver Mage, 2 twooyal Guards/Highwaymen/etc, and a Trapper or Huntsman, plus three regular Mages and a Poacher.

Strategy...
# After leaving your initial chamber, you will be in a large swamp room with three entrances, through which will be a flood of bad guys. Use two Poachers and a Thug or similar to blockade the southeast, a small elite group to block the north, and then a mix of fighters and mages to handle the west entrance. Give each group a White Mage or Mage of Light, as well as at least one regular Mage. Try to keep the Mages of Light away from your chaotic forces on the front lines, though. Use the leadership of Haldric and Lady Jessene - and Mage of Light illumination or lack thereof - to get the most from each attack.
# When the initial battle has died down, you have two options:
## If you have enough forces, you can divide into two groups and attack both brothers simultanously, east and west.
## Otherwise, do them one after the other, and then look for the exit.

Spoilers...
* Danger: there is a Giant Spider at the exit. You may wish to keep one or two cannon fodder units in order to be able to save your advanced units. It is best to use ranged attacks against the spider, so leveled mages are good here.
* Heads up: the next scenario is a lot easier with a lot of gold, especially on the hardest difficulty level.

===Southbay in Winter===

Plot only.

===A Final Spring===

This is a large battle, and any mistake on any front can spell doom, but overall it will be fairly easy on the easier difficulty levels. On hard, it will only be a cakewalk with a lot of starting gold (more than 450 or so.)

Recruitment...
# On the first turn, recall a Silver Mage to teleport to the island, recruit Footpads for village snatching, recall one or more of your loyal Iron Maulers (leveled up Heavy Infantrymen from ''The Fall''), and recall one or more Knights or similar.
# Second turn, continue with this theme, but it will be nightfall soon, so recall Outlaws, Bandits, Assassins, etc.
# Turn three is a bit more of the same, but you need to start thinking about preserving your income and also keeping a gold reserve. You can spam some peasants to preserve cash and income.
# Turn four turn is more of the same.
# Turn five is similar, but it will be day soon, so lawfuls like Knights and level 1 Mages are a good idea.
# Turn six, you will have new recruitment options (see spoiler at walkthrough end.)

Strategy is broken into four fronts...
# The first front is the south land area. Do a counter-clockwise sweep with mounted units, optionally augmented with Footpads, which can help pad out your lines with forest and village hexes. Note that it will be nightfall soon after game start, so it might be wise to delay any serious mounted assault until the next day, and you can delay your recalls for this.
# The second front is the walled city. Move slower units and your loyal White Mage / Mage of Light to defend here. Take your ally's villages; your ally wouldn't do much useful with the money anyway. When your mounted units from the second front complete their sweep, you can break the remaining southern forces against the city wall in a hammer and anvil. Then your united forces can move north. On easy, you may be able to push north more quickly than that using just part of your city troops.
# The third front is the bay and peninsula north of your keep. If you don't protect this area well, Wolf Riders and others will mount an amphibious assault in an effort to flank your troops. On the easier difficulty levels, you may wish to beat the punch and quickly establish a bridgehead on the other side of the bay.
# The fourth front is the two small islands. Send a Silver Mage there ASAP. (You should have a village already there, so the Silver Mage can teleport over.) Footpads/Outlaws/Fugitives and others will help later. Lady Jessene could be used. A quick White Mage would be useful, either on the coast or on the islands. Do not use Assassins on this front. Assassins have relatively weak defense in water against Orcs and Nagas, they're very weak against blade, which is all orcs and nagas use, and their relatively slow movement in water makes backstab hard to use reliably. Overall, you need to devote more resources to this front than you might think.

Hints...
* You should have lots of high-level units now, so concentrate on recruiting new ones and levelling them up to fill needs.
* Peasants are useful as placeholders for villages and distractions for the enemy.

Spoilers...
* On turn 5, a gang of nasty undead show up in the east. So, for your city taskforce, you'll want to recruit/recall units with impact and arcane attacks. Note that if undead capture villages, they will be flagged with the Orc island boss' black flag! This can result in an overwhelming number of Nagas, and it's one reason that you must devote a lot of resources to the island campaign. Flag any black flag villages you can.
* On turn 6, a gang of nasty Mermen show up in the west. Fortunately, they are on your side. You can now recruit Mermen. This is the real reason to keep a gold reserve until this time.

===Peoples in Decline===

This is a bloody scenario versus Drakes. It can be a real challenge on the hardest difficulty setting, less so on the easier levels. Proper recruitment is more important than strategy here, as you will have little opportunity to maneuver.

Recruitment...
* Drakes can be dangerous, so this is a great scenario to use the time honored technique of cannon fodder. Now that you can recruit level 0 units for cheap, you can protect your higher level units by recruiting endless Peasants to distract the Drakes' firepower.
* Drakes are vulnerable to pierce attacks, so spam cheap pierce attack units. In addition to Peasants, there are Poachers, Bowmen, Peasants, Spearmen, Merman Fighters, and Merman Hunters. Poachers are key here, due to the swampy terrain and their chaotic alignment.
* You will need about 3 White Mages / Mages of Light in all.
* On your last turn of recruitment when you have about 80 gold, recall some advanced units, like Master Bowmen.

Strategy...
* Since you will have a lot of level 1 and 0 units, make sure to use the leadership of Prince Haldric and Lady Jessene.
* Look for opportunities to heal via leveling up.
* Pay attention to the day-night cycle in this scenario. Drakes will be strong during day, but become very weak in the night.
* Take advantage of the mountains for defense, but note that on hard, you need to set up a relatively small perimeter around your base, as you will be hard pressed to even hold a small area.
* Be careful with your loyals.
* Because most Drakes have powerful ranged attacks, the roles of your melee and ranged units are reversed from the norm. Whereas usually you would use fighters to protect archers, here you will use archers to protect fighters. Melee-only units should hide behind the lines until they attack, preferably at night (with a Mage of Light supplying illumination.)

Spoiler...
* Make sure you get the Storm Trident in the middle of the sea, but be certain that you've cleared most of the Drakes first, since a Sea Serpent will appear. It's best to have some strong units ready to kill it in 1 or 2 turns. You can give the trident to Lord Typhon, but since he leaves a bit later, you may want to give it to another Merman Fighter. Movement over land is important for Mermen in the campaign as a whole. If the Merman Fighter to whom you give the storm trident has the Quick attribute, you can make him a Hoplite when he gets to level 3. Otherwise, make him a Triton, because movement over land is important for Mermen in this campaign as a whole.

===Rough Landing===

You will be fighting Nagas and Vampire Bats, primarily. This is a scenario that may be frustrating on the easier difficulty levels, though on hard it is just par for the course. Good recruitment and strategy will save you from getting slaughtered.

Recruitment...
* You are probably going to go negative on gold and be unable to rectify that with the paultry early finish bonus, so you might as will go very negative and be resigned to start the next scenario with minimum gold.
* Recruit/recall many Mermen and 1 or 2 White Mages or Mages of Light. A few Peasants can be useful to pad out your force, distract the enemy, and protect villages from stray Bats. A Silver Mage can be useful for island hopping but is not essential. Thieves/Assassins are blade vulnerable, and Nagas only use blades, so it's probably best not to recall them.

Strategy...
# Knock out the southeastern leader in a blitz. It's important to get that out of the way, because a wave of Nagas is advancing at light speed from the north.
# Next, hurriedly set up a line in the water alongside your fortress island. Your fortress troops can anchor one flank, while Burin the Dwarf can go to the island to the northeast to anchor the other end of your line. Nobody messes with Burin. Move Lady Jessene behind the lines to lend her support to the Mermen. Your loyal Mage of Light will be able to move back and forth more (to lend illumination) if kept in the fortress area.
# Finally, once the enemy assault wave has been broken, advance northward to kill the final two leaders in a straightforward mop-up operation. Just be careful not leave isolated units where they can get swarmed.

Hints/Spoilers...
* Try to level up the mermen; they can be useful in another scenario later.
* Beware of Sea Serpents. Three of them will appear, one on each of the three turns following your first kill of an enemy unit. Make sure to kill them at once. The Storm Trident from the previous scenario and the Ruby of Fire will come in handy against the Serpents.

===A New Land===

This is a non-scenario. The scenario objectives tell you to avoid all confrontation for as long as possible, but actually the faster your units encounter the others the faster the scenario will end.

Recruitment...
* None necessary.

Strategy...
* The optimal strategy for gold carryover is to grab the three closest villages, then retreat to your keep and wait. Once one attack occurs, the non-scenario will be over.

Spoiler...
* One thing to keep in mind is that this the last chance you have to grab some more Mermen as their king leaves. They are quite helpful in a later scenario so grabbing a few extra here cannot hurt if you can spare the gold.

===The Ka'lian===

Story, with your choice of four battles next. You have to beat them all in whatever order. The amount of gold you have should be the factor in deciding when you choose to play Cursed Isle (the undead problem).

===Diverging Campaign Path===

All four scenarios have to be beaten, but in whatever order you choose.
====The Dragon====

This scenario is not as difficult as it looks, though your recruitment and strategy need to be tailored to fight the Saurian Skirmishers and other foes you will face here.

Recruitment...
* Saurians use piercing attacks mostly, so it's better to use units resistant to pierce. Pikemen and Halberdiers have 40% pierce resistance. Javelineers are ideal as Saurians use ranged attacks a lot.
* You may wish to bench some or all of your loyal Iron Maulers. They are ineffective against the 70% impact resistant Mudcrawlers, while also vulnerable to the ranged attacks of both Mudcrawlers and Saurians.
* Consider adopting a force of all units with ranged attacks, save for horse and thief units, which can be kept behind the lines when not in use. It is amusing when Saurian Augers are forced to tap your units with their little staffs.
* Healers are a necessity to deal with the heavy damage your units will be sustaining. Depending on the strategy you adopt, you will want 2-4 healers. Mages of Light rock here, as they can easily do front line duty in pairs and their illumination blinds the Saurians, reducing their damage.
* You need something to clean up mud. Versus level 0 Mudcrawlers, Horsemen and their advancements can charge with no counterattack, and likewise Thieves and their advancements can backstab with no counterattack. Mages can be used as well on the fire vulnerable mud.
* A Merman or two will help with water hexes. An Entangler's slow ability will help tame the dragon.

Strategy...
* Players have used many different strategies with success:
** "Hedgehog" strategy: Fighting Saurians requires a disciplined formation. If you're used to stringing out troops to move them into position as they get there, that won't work after Turn 2 or 3. You can use a "healing hedgehog" of ten troops--two white mages next to each other and eight troops completely encircling them. If someone gets badly injured, move them to the inside and put a white mage on one of the long edges, fighting as you go. If you're trying for the big bonus, you'll need two hedgehogs. Try to keep reserves back a bit in cities. If the terrain favorably protects you, or the wounded is a fast unit, you can try moving wounded back to cities too. Once the main wave of Saurians is broken, you can string non-wounded troops out a bit in the rush for the leaders.
** "Triangular Hedgehog" strategy: Switching wounded units to the inside of the hedgehog can be a problem if you are surrounded. ZOC prevents you from creating an open hex to move the inner unit into. You can fix this by creating a triangle with three hexes inside, instead of the standard two of the hedgehog. If you do this on your castle, only three units are in grasslands. If you set it right, you can make most of the hexes adjacent to your triangle be grassland as well, forcing the Saurians into a bad defensive position. In terms of unit positioning, the simplest way is to fill two inner spaces with Mages of Light, a but a better tactic is to put one of the mages on an edge, thereby ensuring that all but one of your units are healing. The remaining unit can either be a Merman Hoplite, (prefereably resilient and carrying a Storm Trident) or Lady Jessene, since she has excellent defense and is chaotic and therefore benefits by not being in the Mages' light.
** "Giant Hedgehog" strategy: Recruit a lot of units, and then move the whole army as one big bulk. Keep healers in the middle (about four), rotate stronger units outwards, and make sure you leave no gaps. The Saurians will slip through the tiniest gap and kill your weak units. Head first for the east or wast leader, but steer for good terrain, because your force will soon be swarmed until about turn 10, when there should be many few Saurians alive.
** "Standard Line" strategy: Form a line from the west board edge diagonally up towards your keep across the two villages just in front of the forest. You will probably wish to bend upwards at the forest, rather than running the line all the way to the keep. Whenever the Saurians have a small number of troops at your line and you have enough strength to kill them all, you can advance your whole line one hex south, allowing you to get additional attacks on them from non-frontline troops. Once you advance a unit to the first water hex at west board edge, the west leader will probably come out to greet it, so be ready to fry him with Haldric's ruby. After killing the leader, back up into good terrain to prepare to meet the dragon.
** "Wake the Dragon" strategy: Prematurely wake the dragon (see spoiler below) and back up your troops to north of your keep. When the dragon comes, kill him. The scenario can be over on turn 7. There is no early finish bonus for this, but you can recruit lightly so that you still have gold at the end and will carry-over 40%, if you need it for your next scenario.
* With all these strategies, the Saurians may hold back for quite a while. This is okay, as the Dragon will eventually appear and come to you. Kill it. Then you are given a choice of whether to end the scenario or to try to kill all the enemy leaders before time runs out. You can choose to finish the remaining Saurians for a nice bonus. However, on the hardest difficulty setting the turn limit (33 turns) is insufficient for you to plow through the vast hordes of level 0 spam to get to the leaders, so it's best to simply end the scenario after killing the dragon.

Spoilers...
* The dragon will awake on turn 15 or when you move a unit down around the road north of the mountains. If you wish to wake the dragon prematurely, you can recruit a Horseman on turn 1 and run him down. It's a suicide mission for him, however.
* If you have a fast non-horse unit in position, rush it to the mountain cave after the Dragon leaves to grab the 200 in gold, though that's nothing compared to the Hero bonus for defeating all the Saurian leaders. So focus on killing all of them first.

====Lizard Beach====

This is a scenario versus Saurians, Giant Scorpions, and Mudcrawlers, where good recruiting and strategy will save you from massive bloodshed.

Recruiting...
* Mermen are helpful for the swamp and water areas.
* Bench some or all of your loyal Iron Maulers, veterans from ''The Fall.'' They are laughably ineffective against the impact resistant Mudcrawlers - and laughably vulnerable to their ranged attacks.
* Thieves, Horsemen, and their advancements are good for mud cleanup, though you must keep them out of range of Saurian skirmishers. Swordsmen and Royal Guards are also good, though overkill.
* Recall a lot of fairly high HP units, preferably with strong non-impact ranged and melee attacks.
* Mages are good. Mages of Light are especially useful, since they can do front line duty. Lots of healing may be necessary, about 3 healers are good, so White Mages can be used too. Raw recruit Mages can be used as well, for disposal of Giant Scorpions and the occasional Saurian Skirmisher that wanders too far. At least one Silver Mage is highly desirable, along with a speedy unit (e.g., Fugitive, Footpad, or Horseman) to capture villages for the Silver Mage to use north of the river.
* [fredbobsmith2] An alternative strategy that works surprisingly well is to simply use a very mage-heavy army. Recall most or all of your high-level mages, throw in a few peasants, and spend the rest of your gold on recruiting mages. Victory will come with shocking ease.

Strategy...
* General strategy: as Saurians have skirmishers and a lot of movement, be sure to protect your wounded units well. Because of the Saurians unnerving ability to concentrate their fire on one unit, be sure to keep several healers around and try to keep your line straight so only two can mob one guy. Hedgehog tactic also seems to work well.
* Opening strategy: here are some specific strategies that players have used with success in the early part of the scenario:
# "Mermen in center" strategy: Recall 2-4 Mermen, 1-2 Trappers/Huntsmen, and a lot of high HP troops, then form a line. Initially, you can either form a north-south line around the lake area with one flank at the south board edge, or, if you want to be conservative, you can do a diagonal line in the southeast corner, with both flanks tied to board edges. You'll need the Mermen to handle the lake area, and Trappers/Huntsmen/Mermen for the swamp areas. Keep troops in reserve, so that when a few Saurians meet your line, you can advance your whole line over them. Do not be too conservative/defensive on hard, as your time is limited.
# "Mermen on flank" strategy: Recall several decent land melee units & then 4-5 level 2 Mermen on rounds 2-3. Most of your force forms a line of battle near your keep, Mermen on the north flank in the river, land units extending south, flanks bent back with strongest units at the corners - then let the Saurians break on it. Once their first wave has broken, the rest of their troops come in drips and are no problem, so now you can split up and wipe out the stragglers and claim villages; any L2 units you start with should level up. After you defeat the main force from the south send just one or two guys north to capture towns so your Silver Mages can teleport into the fray.
# "Mermen feint" strategy: Recall most of your Mermen from before and send them along the river towards the sea. This will harry the saurian troops coming down from the north, allowing your main force to advance on the southern enemy undisturbed. Beware, though as your mermen will encounter the Saurians at night time (giving you -25% and them +25%), so try to minimize conflict until dawn, just get in their way.
# "No Mermen" strategy: On your first two turns recall two keeps of strong, fast veterans like mounted units (not Paladins though; they're pretty ineffective against saurians), Outlaws/Assassins, and Silver Magi along with some other veterans, preferably with a lot of HP: if all goes well (at least on easy and medium) that may be all you need. Dash them across the swamp directly west of your keep, south of the sands, and form a line with strong units at the ends. They'll flank you, but you're stronger than them and you can use your slower units to crush the flanking saurians in a hammer and anvil. The first wave of southern Saurians should get itself killed before the northern Saurians arrive in force. Once the northern Saurians arrive, take them out with your slower units while your quicker ones go for the southern leader.
# "Sacrificial lamb" strategy: In addition to a couple mages, 2 healers, and some other fighters, recruit a castle-full of peasants to draw the Saurians out onto open ground. Surround a single peasant on 5 sides, with 2 healers behind him. Build your formation around that.
* Closing strategy: The enemy's onslaught tapers out after their initial wave, so the final push for the southern leader should be quick and clean. Taking out the northern leader is harder, because all of your units will be stuck south of the marshes and the river. If you want to go for a quick win, just march forth with Silver Mages, Mermen, and anyone who's close enough to be a help. If you don't want to lose any of your better units, patience may be the key.

Spoilers...
* When one of your units gets as far west as the second bridge, a wave of Nagas will arrive out at sea. You may wish to delay going that far until the second watch, so that the Nagas will make contact with your forces during the day.
* Killing one leader gives more gold to the other, so when you've defeated pretty much all the southern leader's forces, just plant a level 3 or two in his keep and leave him alive; kill them both in the same turn.

====The Troll Hole====

This is a scenario that you cannot win by brute force, because the trolls have more brute force than you. Wise recruitment and strategy are necessary.

Recruitment...
* It's underground time again, so as before, mainly recruit mages. The trolls are strong, so hopefully you have lots of levelled up mages. Mages of Light are especially nice, because they are tough enough to survive an attack from most trolls, while simultaneously reducing the damage sustained (due to illumination blinding the trolls.) Level 1 Mages can be used to good effect too, especially if quick. If only attacked by a single Troll Whelp, a healthy level 1 Mage will survive.
* In addition to mages, your chaotic units can be helpful here again, especially against the occasional Rocklobber, which you will not want to attack with mages.
* Forget about your loyal Iron Maulers (leveled up Heavy Infantrymen from ''the Fall''). They are too slow. It's not that you'll be running around, but you will be rotating troops due to heavy damage, and they will only get in the way.
* Putting Mermen in the moat will really help you fend off the first wave of attacks.

Strategy...
* There are 4 castles, and two of them (randomly placed it seems) are the troll leaders you need to kill.
* Try to use the narrow corridors to your advantage, so the enemy can only place one attack against a strong unit of yours, but you can kill a troll at a time with two mages or Haldric. Also keep an eye at your back since they will try to surround you. And resist the temptation to send single units wandering around in what seems empty caves - they will all die, probably by the fangs of a Giant Spider.
* Try to arrange it so one troll can enter to be attacked by many troops. Have regular troops in front initially. Move mages forward to finish the troll, plug the gap where the troll was with Burin or a Royal Guard or an Iron Mauler, and reset the trap on the next turn. When you've whittled down the enemy, go the direction they came from and kill the leaders, ignoring spider keeps.
* Alternative: This could be a good choice if you have low gold: recall 2 quick red mages, and 3 quick tough melee units (say 2 royal guards & a L3 chaotic unit like a Fugitive). Play expedition style: abandon the start island, stay fairly close together, with your troops roughly divided in two between those moving forward and those fighting rearguard. Provided you knock out one troll leader early, the rest is manageable, just work your way carefully over to the other.

====Cursed Isle====

You will be fighting undead, mostly of the incorporeal and ghoulish lineages. Victory comes surprisingly easily.

Recruitment...
* Recruit lightly, certainly no more than two castles of troops. You could use 1-3 Paladins, 1-2 Mages, and 1-2 White Mages / Mages of Light.
* Recall your loyal Merman Triton or similar and have him pick up the holy water.

Strategy...
* This can be the first or last quest you choose. If you can wait, do it last, as you will come out of it with a lot of gold, which you will need for the first scenario after the quests, ''The Vanguard''.
* Keep a very tight formation for the first night, as Shadows will hit hard and you don't want to get backstabbed or swarmed. By dawn, it should be smooth sailing.
* If you get anywhere near the enemy leaders' keeps, expect to get rushed by a leader.

Spoiler...
* In one of the three temples there is a Vampire Lady. All you really need is a Paladin or three to rush the temples. Kill her. Game over, you win. One of the other temples has some gold; grab that first.

===A Spy In The Woods===

Plot only.

===The Vanguard===

You will be fighting a large number of orcs, trolls and other enemies in a location with a natural defensive line, where presumably an underground river has carved a line of sinkholes. This scenario will be difficult or impossible with minimum gold (200), but quite doable with a large amount of gold (450+) even on the hardest difficulty setting. Recruitment and strategy are fairly straightforward, given the board layout.

Recruitment...
* Recruit a lot of units; you will need them.
# First turn, recall/recruit speedy units: Knights, Lancers, Paladins, Horsemen, Outlaws, and similar.
# Second turn, recall your loyal Iron Maulers (leveled up from ''The Fall'') and Spearmen/Swordsmen/Royal Guards.
# On subsequent turns, recall/recruit healers and other sorts of Mages, Thugs and their advancements, and Longbowmen. You will need quite a lot of healing power: 3-4 White Mages / Mages of Light and 1-2 Paladins. A Silver Mage would come in handy, since your forces will be widely spaced, but you could start with a couple of Red Mages and try to level up one or both to Silver Mage.

Strategy...
# This map is smaller than fog of war and sinkholes make it appear. Rush the west and northwest gaps with mounted units, but slow & strong will carry the day once the sun rises and the odds are in your favor.
# Seal of all the gaps in the ring of sinkholes. When the onslaught begins, wounded units can retreat back into villages or be cared for by healers - or actually both, since soon you will be out of non-wounded units.
# A "Sitzkrieg" may develop, where neither side can make progress. Shift units to the southwest and break out there, using the west board edge defensively. From there, sweep northwards, taking out the western orc leader first and then the next orc leader.
# Don't forget the chest of gold, which you can see even in fog.
# End the scenario with the kill of the final leader, a level 3 troll.

Spoilers...
* Once you kill more than half the units of any side, a few tough undead units will appear near that side's stronghold at the edge of the map. So, this will happen three times. Beware the Chocobones. Their double damage from charge means they can take out Commander Aethyr at night just by hitting 2 for 2, and they will certainly try if they get the opportunity.
* Heads up: the next scenario is much less difficult with extra gold. You can use Peasants to avoid going negative on gold, promoting them to Spearmen only when needed.

===Return of the Fleet===

Welcome to the "kitchen sink" defense. You've made it this far; now the enemy will launch a desperate defense, throwing a little bit of everything at you. The effect is mostly psychological, but it could be a problem if you came into the scenario with minimum gold or your initial assessment causes you to drastically under-recruit. Time is money.

Recruitment...
* On medium, at least, you don't want to overrecruit. First turn, recall Mermen to assassinate the undead leader; 2 Entanglers/Netcasters and the Triton with the Storm Trident. Later, you should recruit 1 or more Silver Mages also for this taskforce as well as for causing general mayhem. It's also worth recruiting 5-10 L1/L0 units to take the brunt of the first wave of attacks; you can use any combination of Footpads, Poachers, Thugs, Spearmen, and Peasants, as you see fit. You'll want some decent L2 and L3 recalls for healing, to flank your lines, and to start kicking some butt at daybreak. A Mage or Red Mage to blast Trolls and Chocobones will level up by end of scenario. Paladins are good too. In addition to your loyal Mage of Light, you will need a bare minimum of 1 more healer.
* On medium, don't recruit too much for fighting the undead - 2 Paladins at most, 1 or 2 Thugs, the stormy Merman, and the nearest Mage working with your land force are sufficient - the undead commander only gets 5-6 L2 recruits and they come ashore scattered (on medium, anyway). Paladins are so effective against undead that you can wade into the water after them. Just remember, Paladins can't go into deep water and undead can.
* On hard, you also don't want to recruit too much for fighting the undead, but it's only because going on an offensive early against them will get you crushed by a Chocobone armada.

Strategy...
# Move the Mermen (including the storm trident) as quickly as possible pretty much straight to the West. (There is a village and swamp hex that can aid your travel if you pick the best route). Move these guys up the West side once they get there to get to the Undead Leader as quickly as possible.
# Your loyal units can do a little village grabbing, but it would be unwise to venture too far north.
# After nightfall, fog will appear; for the rest of the scenario, the map will become shrouded, like in a cave scenario. So while you're still amazingly able to see, note the key terrain features, castle and city locations, and troop dispositions (especially Chocobones.) Also, visually explore the avenues of approach you want to be able to see later.
# The first wave is largely at night and will have Goblin Knights and Pillagers, and later Chocobones and Troll Warriors. The damage they can cause is bone chilling, so make sure to divert their attention with plenty of spam. You want to meet them on the edge of the woodland, while inducing the orcs to fight from the grassland. Footpads and Poachers are handy here, as they have high defense in woodland. Players have had success setting up the initial line in either the north and northeast woodlands, with respect to the castle. Others have succeeded by fighting mostly from the open plain, retaining mobility by leaving the woodlands to their Footpads.
# Once your Mermen have taken an island city, teleport over one or more Silver Mages to help kill the undead leader - in addition to a Silver Mage, you will want the storm trident, a Netcaster/Entangler, plus one more leveled unit to be fairly sure to knock him out in one round. Quick striking like this you end up fighting a lot less undead. You probably end up foddering one of the mermen to the Undead Archers, but the trade off is well worth it. You can keep cycling your mermen up to fight with any orcs or trolls that come into the water. Silver Mages can assist, since they are not needed much in the other part of the fight.
# After the undead leader is assassinated and the first wave is broken, you may advance cautiously due north or to the northwest along the coast and ultimately finish off the two orc leaders.

Spoilers...
* When you are close to the break in the woods at the east board edge, tighten your formation and keep wounded units well away, as a small force of high-level Saurians will appear. Trigger them in daylight if possible, and knock them out fast. Alternatively, you can delay triggering the Saurians as long as possible by moving your force northwest near the water and then onto the small island, though even then it is possible to trigger the Saurians if you are not careful where you step. (Stepping to 10 hexes or less from 34,15 triggers the Saurians.) You can fight the final wave of orcs from the island, then move northeast to the mainland, finally triggering the Saurians.
* Two cuttlefish appear when you approach the north-central island. Assuming you're sending a strike force through the water to knock out the undead commander, you really don't want to trigger these until that force is on the island - the storm trident Merman is the only thing that can stand up to them in water, and they will avoid him to attack more vulnerable units.
* Once you kill one enemy leader, the other gets more gold & recruits a new wave of L2s. This can be useful if you need to kill off surplus L1 units to improve the finish bonus, or if you need the XP more than the gold; otherwise, try to knock out both leaders on the same turn before they can recruit more. Alternatively, if you kill the first one at dawn, the second will be reluctant to attack with his L2s in daylight, and you might jump in and kill him before he uses them.
* Heads up: The next scenario is the final one. Therefore, loyal units are now somewhat disposable. However, you will need plenty of gold. Recruit some Peasants in the current scenario if you need to save some gold. Not only are they cheap, but they have no upkeep and Chocobones love 'em. Send a unit with leadership with them and they can even deal some amount of damage and be used to finish off wounded enemy, though at night you should just let them take the beating passively since otherwise they die too quickly.

===Rise of Wesnoth===

It's the final battle: be patient, recall everybody - the early finish bonus doesn't mean anything. Also, loyal units are no better than other units after your recruitment is finished.

Recruitment...
* You will need at least 300 starting gold, maybe more like 400 on the hardest difficulty level, so if need be, replay the previous scenario.
* To stretch your money, start with loyal Iron Maulers and a couple ready-to-level level 1's and level 2's. Finally, recall as many level 3's as possible.
* Healers: 3-6 Mages of Light / White Mages. Your few chaotic units will appreciate a White Mage.
* Horse units: 2-4 Paladins, 3-4 Knights / Grand Knights.
* Horse escorts: about 3 speedy units, like Royal Guards, Fugitives, and Silver Mages.
* Tanks: at least 6 high HP units, such as Royal Guards, Highwayman, Master Bowmen, and the loyal Iron Maulers.
* Mages: at least 3 high level Mages aside from your basic healers, so Arch Mages, Great Mages, and Silver Mages. Additional Mages of Light can be substituted.
* Some Mermen might be useful here, but surprisingly, they're not really necessary.
* On 1.9.3 and earlier, you can recruit Saurian Skirmishers on medium and Skirmishers plus Ambushers on hard. This appears to be a bug, so ignore the option.

Strategy...
* You will launch a two pronged assault: mounted units will race to the west and then south, while the main army heads due south.
* With your mounted units, race forwards by day and backwards by night.
* Along with the mounted units should go some escorts, speedy foot units intended to kill things like Goblin Impalers, which make even Grand Knights nervous. They would also benefit from a quick Mage of Light.
* Meanwhile, with your tanks and the rest of your healers and support units, form a line or hedgehog in the woods just south of your keep or next to the river.
* Keep your leaders with the main army, to avoid drawing too much attention to the mounted detachment.
* Maintain awareness of the overall battlefield. If the main army gets in trouble, you can send some or all of the mounted units to assist. There may be an opportunity to hammer-and-anvil enemy forces trapped in the middle. And you may wish to transfer units, like Paladins may be useful to the main army after it is on the move.
* You'll need at least two Paladins to kill Jevyan himself; nothing else is half as effective (except perhaps Mages of Light and suicidal Lancers). Or you can use a pair of Great Mages (unless you are very unlucky, you should be able to kill him in a single turn). Don't forget to sacrifice Aethyr to Jevyan. If he doesn't want to come out and play, march up to Jevyan and use a crossbow attack. When Jevyan is dead, the yellow and green leaders may still be alive. You'll have to kill one, leaving at least one orc leader alive. You pick. Congratulations! Enjoy the ending!

Spoilers...
* When one of your units is within 8 hexes of a bridge, but you have no units within 2 hexes of the bridge, and there are no units on the bridge, then a Cuttle Fish will appear and destroy the bridge. This is usually disadvantageous. Not only does it leave you with a Cuttle Fish to fight, but it slows your progress south and the bad guys progress north. At least on the hardest difficulty level, it's hard to kill all the spam in time, so you don't want to impede their advance by removing the bridge.
* When any of your units is killed, it becomes a Walking Corpse. On hard, it becomes a Soulless, which makes it important to be careful with your level 2's, especially Lancers.
* After the first orc leader is killed, then some gold goes to mister Lich. It's 40, 80, or 120 gold, for easy, medium, and hard, respectively. The lich will receive some gold once you kill his Familiar.

== See Also ==

* [[MainlineCampaigns]]

[[Category:Campaigns - The Rise of Wesnoth]]
[[Category:Campaigns - Walkthroughs]]

Guide to UMC Content

2013-06-11T16:58:40Z

Anonymissimus: /* The Earth's Gut */

''This is a guide to the current (1.10.x/1.11.x) UMC campaigns for players. It aims to provide all the information not only about the story, but also about completion, difficulty and playing style of the campaign. See also [[Guide_to_UMC_Campaigns/Players_Reviews|Players Reviews]], as well as http://forums.wesnoth.org/viewtopic.php?f=8&t=37476 for further information and http://forums.wesnoth.org/viewtopic.php?f=8&t=36733 (for currently non-available UMC-content). Please edit, it is a wiki.''

=== Blueprint ===

'''Status:'''
* Broken = Does not work at all
* Incomplete = Partially written, no progress
* WIP = Partially written, progress
* Complete = Completely written, but buggy as well as potential balance issues.
* Finished = Completely written, minimal to no bugs, slight balance issues possible.

'''Length:'''

'''Author:'''

'''Maintainer:''' if not maintained by the author anymore.

'''Description:'''

'''Version: '''

'''Requirements:'''

'''Difficulty:'''

Please note: Often campaigns introducing new mechanics are listed as expert level on the add-on server, here difficulty means the raw difficulty after the mechanics are understood.

* Unbalanced = If you can't beat the hard mode, it isn't necessarily unbalanced, but if the difficulty changes erraticly from one scenario to the next and only people using the debug mode have seen the final, then it is.
* Easy
* Normal
* Hard

'''Style:'''

Please note: Many campaigns will feature more than one style. Please list the most significant ones.

* Skirmish = small to medium sized armies, your standard Wesnoth gameplay
* Dungeon = long and narrow tunnels (not every underground scenario is a dungeon, a dungeon isn't necessarily underground)
* RPG = role playing game elements such as talking with non-player-characters, item collection, dependency on a party of very few adventurers without or limited recruits
* Survival = being exposed to changing, spawning enemies while remaining on the same map
* Large Battle = large number of units on the battlefield, sizely maps
* Simulation = campaigns feat. terrain modification, alternative resources
* Boss battle = the challenge is to defeat a single powerful enemy unit
* Minigames = there are puzzles and minigames in the campaign that significantly differ from standard Wesnoth gameplay

'''Faction/Era:'''

* Era for the whole campaign and more specifically the faction or unit composition you field.

'''Custom units:'''

* Link to the unit tree for cases that don't feel sufficiently described by Faction / Era entry.

'''Forum:'''

* Links to the feedback and development threads at forums.wesnoth.org

== Battle for Wesnoth 1.10.x - stable ==

''Campaigns available in the 1.10.x stable version.''

=== After the Storm ===

''Follow the journey of Elynia and her band following the events of Invasion from the Unknown''

'''Author:''' shadowmaster/ShikadiLord

'''Status:''' Finished

'''Length:''' 3 episodes of approximately 12 scenarios each, some of which are multi-part

'''Difficulty:''' Medium-hard

'''Style:''' Skirmish, Boss Battle, Dungeon

'''Faction/Era:''' Many custom units

'''Version:''' 0.9.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=32091

'''Note:''' (vultraz) Long, very enjoyable campaign with great story.

=== Aldur The Great ===

''This is a story about Aldur the Great.''

'''Author:''' pintercsabi

'''Status:''' Complete, but unbalanced

'''Length:''' 5 playable scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default

'''Version:''' 1.2.2

'''Forum:''' -

'''Note:''' (Adamant14) Short unbalanced campaign, maybe abandoned. You fight with Peasants, Ruffians and Woodsman against Orcs

=== Alfhelm the Wise ===

''This is the tale of Alfhelm, called by some the Wise, son of Alfric Conqueror. This is the tale of his victories over his enemies, and his rise to power in the clans of Marauderdom. This is the tale of his journey south and his destruction of the Lavinian Empire. And this is the tale of his demise in the dark forests far to the east of his homeland.''

'''Author:''' turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 15 gameplay scenarios

'''Difficulty:''' Moderate

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Marauders.

'''Version:''' 0.6.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=17144

'''Note:''' (Maintainer) Though this campaign is complete and playable the whole way through, the code is four years old and pretty buggy. If you notice any errors while playing, please let me know and I'll incorporate the fixes into my next revision as soon as possible.]

=== A New Order ===

'''Author:''' szopen

'''Status:''' Finished.

'''Length:''' 45 scenarios.

'''Description:''' The old kingdom of Wesnoth has fallen before barbarian hordes. The occupying barbarians are on the brink of civil war, the seeds of Wesnothian rebellion are kept alive by old legends, while bandits and Khalifate mercenaries roam the land. Can Gawen Hagarthen unite these disparate factions against a common foe?
Note: This campaign contains mature themes, some of which may be unsuitable for children.

'''Version: ''' 1.2.15

'''Requirements:''' Requires BfW 1.10. In addition, you have to install Era Khalifate add-on; the Akladian Music package is optional

'''Difficulty:''' Normal

'''Style:''' Skirmish, Large Battle

'''Faction/Era:''' Akladians, Khalifate

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=6486

'''Note:''' (Pyrophorus) Certainly one of the most mature and well designed campaign in add-ons. A must.

=== Antar, Son of Rheor ===

''This is the story about a young Lord and his first mission; sent by his father the young Lord Antar has to relieve his neighbours; he has to convince the Elves and Dwarves to ally him; he has to fight against hordes of Orcs and Endless Undead; and finally he has to defeat Mal Kazur, the mastermind who is behind all the evil.''

'''Author:''' Adamant14

'''Status:''' WIP

'''Length:''' 9 playable scenarios / 1 cutscene

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Loyalists and Elves (feat. fencer as main hero + various allies)

'''Version:''' 0.9.9

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36075

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Antar.2C_Son_of_Rheor Players Review]'''

=== A Story of the Northlands ===

''A story of life and death in a remote village of the Northlands. Your village has been overrun by an orcish raid. You fight for its freedom while you wait for help to arrive.''

'''Author:''' zepko

'''Status:''' Complete

'''Length:''' 10 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default + additions: you play with a custom faction of outlaws and with a custom party of loyalist knights.

'''[http://units.wesnoth.org/1.10/A_Story_of_the_Northlands/en_US/A_Story_of_the_Northlands.html Custom Units]'''

'''Version:''' 1.0.0

=== A Vision Blinded ===

''Defend the northern forest against what appeared like a routine orcish raid, and unravel the greater conspiracies that lie below its waves.''

'''Author:''' LemonTea

'''Maintainer:''' AxalaraFlame

'''Status:''' Complete

'''Length:''' 13 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves (+ Trolls, Outlaws)

'''[http://units.wesnoth.org/1.10/A_Vision_Blinded/en_US/A_Vision_Blinded.html Custom units]'''

'''Version:''' 0.6.6

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23463&hilit=a+vision+blinded

=== Bad Moon Rising ===

''An expedition to gather treasure from the cold north sets off compounding disaster.''

'''Author:''' Doofus-01

'''Status:''' Finished

'''Length:''' 20 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Archaic Era

'''Version:''' 1.4.4.a

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=31348

=== Battle Against Time===

''Rescue fellow orcish warchief before he is executed. (This is not a normal campaign. It is experiment with carryover system. You will start with defined number of turns and gold. You will only have that many turns to play through the whole campaign. There is no finish bonus and gold carryover is always 100%.)''

'''Author:''' Wonderboy

'''Status:''' Complete

'''Length:''' 4 playable scenarios + 1 prologue scenario

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default: Orcs

'''Version:''' 1.0.0

'''Forum:''' http://wesnoth.org/forum/viewtopic.php?f=8&t=27319

=== Besieged Druids ===

''A elvish school for druids comes under attack by goblins. It seems more than just a routine raid; is there something more sinister behind this attack? - In Beseiged Druids, you control Eärendil, the surviving teacher at the school, and the many and varied initiates. Not all of these are ordinary students; many have been experimenting with other forms of magic, while others are simply overachievers in some area of study. Unfortunately, they are not especially good at combat, at least initially. Together with a very small contingent of surviving guards, it is up to these students to save the island of Aleron from disaster.''

'''Author:''' Celtic Minstrel

'''Status:''' Complete

'''Length:''' 9 scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''[http://units.wesnoth.org/1.10/DruidSiege/en_US/celmin-druid-siege.html Custom units]'''

'''Version:''' 1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37342

=== Birth of a Lich ===

''This is the life story of the dreaded lich Malifor, his struggle as a mage outcast, the orcish conquest of the northlands and his transformation to quench the thirst for revenge''

'''Author:''' chak_abhi

'''Status:''' Finished

'''Length:''' 12 playable scenarios / 2 dialogue only

'''Difficulty:''' Normal

'''Style:''' Skirmish, Large Battle, Dungeon

'''Faction/Era:''' Human outlaws, dwarves, undead

'''[http://units.wesnoth.org/1.10/Birth_of_a_Lich/en_US/Birth_of_a_Lich.html Custom Units]

'''Version:''' 1.0.3

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37057

=== Bitter Revenge===

''Amidst the strife and turmoil of the first Dark Age of Wesnoth, a time of transient monarchies and conspiracies against the Crown, the boy Darith witnesses the murder of his father by a general of Wesnoth. Follow Darith's quest for retribution in this treacherous tale of betrayal, deceit, love, remorse, and vengeance.''

'''Author:''' Wonderboy

'''Status:''' Complete

'''Length:''' 11 playable scenarios + 4 dialogue only

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default (mostly outlaws and undead, custom units)

'''Version:''' 1.1.0

'''Forum:''' http://wesnoth.org/forum/viewtopic.php?f=8&t=26699

=== Cavanagh The Conqueror ===

''This is the tale of Cavanagh Orc-Foundling, who was blessed by the gods to conquer and unite all of the Great Continent. Orcs and elves, gods and men, queens and sorcerers populate this epic tale of revenge and redemption.''

'''Author:''' TheEmptyLord (Programming, Map-making, Editing), Scott_Free(Story)

'''Status:''' WIP

'''Length:''' 10 Playable Scenarios so far

'''Difficulty:''' Normal

'''Style:''' Skirmish, limited RPG, limited Large Battle

'''Faction/Era:''' Default (Units from Northerners, Outlaws, Loyalists as well as other factions interspersed. Several custom units.)

'''Version:''' 0.1.2

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=35927

=== Cities of the Frontier ===

''Settle a new town in the wilds north of the Great River.''

''This campaign makes several changes to the standard Wesnoth game mechanics, and focuses on city-building and gold management.''

'''Author:''' esci

'''Status:''' Complete

'''Length:''' Not fixed, approximately 6-10 seasons of 36 turns each

'''Difficulty:''' Normal

'''Style:''' Simulation, Survival

'''Faction/Era:''' Default, Loyalist

'''[http://units.wesnoth.org/1.10/Cities_of_the_Frontier/en_US/Cities_of_the_Frontier.html Custom units]'''

'''Version:''' 0.5.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36004

=== Considerate Dead ===

''As the wind goes on and on, people discover necromancer aren't always bad. Made by tribes45 - No scenarios are done, 4 playable out of ??.''

'''Author:''' tribes45 aka tribes55

'''Status:''' Incomplete, unbalanced, abandoned

'''Length:''' 5 scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default

'''Version:''' .009

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36522

=== Count Kromire ===

''You are the blood son of a vampire lord, however when the might of the celestial crusades comes knocking, and your father is slain, you flee your lands. However you intend to return, to restore the lands of Kromire to the Kromires, to avenge your father, and most importantly, to make sure that no celestial ever dares come into your mountains again.''

'''Author:''' Velensk

'''Maintainer:''' currently none

'''Status:''' Complete

'''Length:''' 9 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Era of Myths, Vampires

'''Version:''' 1.3.2

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=21560

=== Elvish Dynasty RPG ===

''You are the new ruler of an elvish kingdom! Can you lead your people to glory? This campaign is highly randomized so it will be different every time you play!''

''Sequel to Ooze Mini-Campaign''

'''Author:''' spencelack

'''Maintainer:''' Wesbane

'''Status:''' Complete

'''Length:''' 10 years, in each year choice between dialogue and fighting scenario (selected out of a large pool of possible scenarios)

'''Difficulty:''' Normal

'''Style:''' RPG, Skirmish

'''Faction/Era:''' Default, Elves

'''Version:''' 0.9.9b

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=28627

=== Fall of Silvium ===

''You are Caius Regilius, Tribune of the province of Silvia, located in the northmost reaches of the Lavinian Empire at the height of its power. But the Empire has overextended itself, The city of Silvium lies seperated from the rest of the Empire by the mountains of Arendia, and is sandwiched between the Marauders and the Sidhe... war is inevitable, and the province of Silvia will almost certainly fall.''

'''Author:''' turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 8 scenarios

'''Difficulty:''' Medium

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Lavinian Legion.

'''Version:''' 0.6

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=31&t=24356

'''Note:''' The final level of this campaign is not supposed to be winnable. It's a final blaze of glory and chance to use all your high-powered units, but to 'win' the campaign, you must lose...the ending is similar to a certain mainline campaign, but predates it.

=== Fate of a Princess ===

''Part I: Baldres, a notorious robber baron, flees Wesnoth with his followers and sets off into the northlands to evade the king's justice. The baron's deeds and misdeeds are to change the balance of power between orcs and non-orcs throughout the northlands, and will carry consequences long after his eventual death.''

''Part II: The Greenwood elves face a crisis which demands the return of the queen's estranged half-elven half-sister, Baldres' daughter. Two brave young elves must make a perilous journey to find her and bring her back to her former home. If they fail, the whole northlands will be engulfed in war with the resurgent orcs...''

'''Author:''' SkyOne, mich, simonsmith

'''Status:''' Finished

'''Length:''' 26-29 scenarios (some dialogue-only), 2 parts

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon

'''Faction/Era:''' Default with additions. You play two different, unique cross-faction combinations in each part.

'''[http://units.wesnoth.org/1.10/Fate_of_a_Princess/en_US/Fate_of_a_Princess.html Custom units]'''

'''Version:''' 0.9.17

'''Required Wesnoth version:''' 1.9.12 or later

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=26327

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Fate_of_a_princess Players Review]'''

=== Forgotten Kingdom ===

''Help Orlog, a troll chieftan, lead his people to safety in the underground and discover an ancient power long forgotten.''

'''Author:''' Limabean

'''Maintainer:''' Chrysophylax

'''Status:''' Incomplete ( but all scenarios playable and balanced )

'''Length:''' 9 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Goblins, Trolls

'''[http://units.wesnoth.org/1.10/Forgotten_Kingdom/en_US/Forgotten_Kingdom.html Custom units]'''

'''Version:''' 0.1.7

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23483

'''Note:''' (Adamant14) This campaign includes a custom Troll line. A good campaign, I hope Limabean and/or Chrysophylax will finish it.

=== Forward they Cried ===

''You are the leader of an advanced detachment that has been tasked with capturing a bridgehead while the main army prepares to attack. It should be a simple enough assignment.''

'''Author:''' Glowing Fish

'''Maintainer:''' Lord-Knightmare

'''Status:''' Finished

'''Length:''' 1 scenario ( rather a single scenario than a campaign )

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default Loyalists

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23656&p=350126&hilit=forward+they+cried#p350126

'''Version:''' 1.0.0

'''Note:''' (Adamant14) Only a single scenario, but a great scenario.
(UnwiseOwl) You wouldn't want to stop thinking for a turn, and it's good for the first few turns, but this one leaves me wanting more.

=== Galuldur's First Journey ===

''While the belligerence of orcs is nothing new, their intensifying attacks on a fledgling colony of elves in Pindir Forest begin to show signs of a deeper malice, forcing Galuldur, the young son of the colony's adventurous founder Galur, to venture out of his forest's friendly trees in search of help. His simple errand quickly turns into a frantic quest to unearth the roots of the mysterious evil threatening his people. As you lead him through unknown lands, Galuldur, forced to match wits with unexpected adversaries at nearly every turn in a desperate attempt to save his world, quickly learns that the world is neither a friendly nor a simple place.''

'''Author:''' mattsc

'''Status:''' Complete

'''Length:''' 8-9 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''[http://units.wesnoth.org/1.10/Galuldur/en_US/Galuldur.html Custom units]'''

'''Version:''' 1.1.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=31895

=== Grnk the Mighty ===

''All his life, puny little goblin Grnk the Frail had been dreaming about leaving the orcs and starting a better life. When he finally arrives in the human town of Shmaltupp, he realizes that the world is not as black and white as he had imagined. He also discovers that he is no ordinary goblin. Follow Grnk the Frail on his path to becoming Grnk the Mighty.''

'''Author:''' mattsc

'''Status:''' Part I complete

'''Length:''' 13 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish, RPG

'''Faction/Era:''' Default, changing (no standard army building gameplay)

'''[http://units.wesnoth.org/1.10/Grnk/en_US/Grnk.html Custom units]'''

'''Version:''' 1.0.5

'''Required Wesnoth version:''' 1.9.5 or later

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34970

=== Invasion from the Unknown ===

''Episode I - Seeking the Light: Long after the Fall, the last forest elves are forced to abandon their safe valley, and find themselves resorting to the dark means of necromancy in order to survive the perils and challenges of this new harsh world. May they finally free the Great Continent from its chaos, or perish in the foolish attempt of restoring peace and life to the lands.''

''Episode II - Armageddon: As the shadow of Chaos covers the entire continent, an assorted group of foolish heroes prepares a counter-attack to the Empire, with one unique goal in their minds: defeat the evil Emperor, whoever it is. Lead these courageous living and non-living warriors to victory, and rediscover lost secrets of the history.''

'''Author:''' shadowmaster

'''Maintainer:''' Espreon

'''Status:''' Finished

'''Length:''' 26 scenarios in two episodes

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon, Boss battle

'''Faction/Era:''' Unique. You play Elves and Undead throughout the campaign + in the 2nd part Northerners and Aragwaithi.

'''Version:''' 1.90.6

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Invasion_from_the_Unknown Players Review]'''

'''Note:''' (taptap) Despite its acknowledged flaws (generic hero, plot holes, deus ex machina moments, gameplay issues in the 2nd part) this is undoubtedly the most iconic campaign in UMC. It single-handedly redefines the elvish history and sketches a cosmology for the ages after the fall. With the Chaos empire and its various allies it introduces an era worth of factions to single-player play. At the same time it features some of the most beautiful maps in Wesnoth and stunning art on par with mainline campaigns.

=== Invasion of Eliador ===

''A peaceful island is about to be invaded by unknadd-ons foes travelling towards the eastern shore. It is up to a family of outlaws to warn the island's inhabitants before it's too late.''

'''Author:''' Sam M. (Genosuke)

'''Maintainer:''' trewe

'''Version:''' 1.0.4

'''Style:''' RPG, Skirmish, Puzzle

'''Length:''' 10 scenarios + epilogue

'''Difficulty:''' Easy

'''Status:''' Complete

'''Faction:''' Default (outlaws)

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=6556

'''Wiki:''' [[Invasion_of_Eliador]]

=== Langrisser Sample Campaign ===

''The Imperial Knights of the Rayguard Empire have disrupted the peace of the village that was Hein's hometown, seeking only a girl named Liana. Fight to rescue Liana.''

'''Author:''' Morath

'''Status:''' Finished

'''Length:''' 1 playable scenario

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''Version:''' 0.1.0.5

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36417&hilit=Langrisser

'''Wikipedia:''' [http://en.wikipedia.org/wiki/Langrisser What is Langrisser]

'''Note:''' (Adamant14) Single scenario, different from usual Wesnoth behaviour.

=== Legend of Far North ===

''The tale of the legendary Black Eye Karun,depicting his rise to power, his successes and his brutal assassination.'

'''Author:''' chak_abhi

'''Status:''' Finished

'''Length:''' 16 playable scenarios / 1 dialogue only,1 cutscene

'''Difficulty:''' Normal

'''Style:''' Skirmish, Large Battle

'''Faction/Era:''' Orcs, Trolls, Saurians, Nagas

'''[http://units.wesnoth.org/1.10/Legend_of_Far_North/en_US/Legend_of_Far_North.html Custom Units]'''

'''Version:''' 1.0.2

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34769

=== Legend of the Invincibles ===

'''''Part I: Shrouded in Darkness''' (5 chapters, 90 scenarios) - A pair of heroes, after stopping an orcish thread, are outcast into caves, where they have no other choice than to become liches in order to survive. They preserved their original appearance and moral principles, and fight in various skirmishes against evil (although using evil methods sometimes), until the Fall, when they are buried alive under the ashes of the third sun.''

'''''Part II: Into the Light''' (4 chapters, 96 scenarios at the moment) - Long after the Fall, the lich heroes awaken. Searching for more power, they manage to resurrect themselves as living beings, but this time more powerful and ridden of the evil within. But the evil from inside them did not cease to exist, and started a campaign to conquer the world. Stopping the campaign caused an even worse disaster...''

'''Author:''' Dugi

'''Status:''' WiP (but Part I might be considered complete)

'''Length:''' 185 (+7 talk-only) scenarios at the moment

'''Difficulty:''' Normal

'''Style:''' mostly Skirmish and Dungeon (all other styles are present as well, but less frequently)

'''Faction/Era:''' Elves, Loyalists, Undead, Dwarves; but they advance past their usual maximum level

'''Version:''' 2.5.0

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Legends_of_the_Invincibles Players Review]'''

'''Note:''' The most unique feature of this campaign is its RPG-like unit development system, enemies drop items units can use, leaders are stronger than most usual units and all units get AMLA (after maximum level advancement) after reaching their maximum level (that is also increased by a load of additional level 4 units).

=== Panther Lord ===

''The Imperialists ambitions of pushing into the Sea States have been repeatedly thwarted and now they turn their attentions elsewhere. You are an outcast Darklander now living as a mercenary in the Sea States and the rumors you hear indicate that they will be coming to your people. Though an outcast you do not wish to see them subjugated. The spirit whose friendship caused you to be an outcast has a plan that might allow you to save them.''

'''Author:''' Velensk

'''Maintainer:''' Lavender

'''Status:''' Finished

'''Length:''' 14 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Era of Four Moons, Darklanders (+ a wide variety of mercenaries)

'''Version:''' 1.0.2

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34318

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Panther_Lord Players Review]'''

=== Random Campaign ===

''Gain experience playing the Default Era faction of your choice in a campaign setting''

'''Author:''' SigurdFireDragon

'''Status:''' Complete

'''Length:''' 7 playable scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Age of Heroes, & Era of Legends

'''Version:''' 1.0.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=32922

'''Note:''' (Author) A 4 scenario version is under the multiplayer button, which lets you choose any era.
Intended for players to gain practice with a faction and learn sound strategies using faction specific adjustments against random factions from the chosen era.

=== Rebellion in the North ===

''A great orcish uprising tends to destabilise the Northlands. As the future Lord Protector of the Northern Alliance you have to crush the rebellion and establish peace again."

'''Author:''' chak_abhi

'''Status:''' Finished

'''Length:''' 24 playable scenarios / 3 dialogue only,2 cutscenes

'''Difficulty:''' Normal

'''Style:''' Skirmish, Large Battle

'''Faction/Era:''' Loyalists, Dwarves, Gryphons, Merfolk

'''Version:''' 1.1.12

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=33059

=== Return of the Monster ===

''It was time for Amailoss, born from the naga queen's last egg, to leave home. Time for him to grow into a leader in his own right, and eventually become the guardian and leader of another naga city. But along the way, he became friends with an unusual mud-crawler, they met a strange young monster, discovered that a spirit had escaped from an orc prison, and the mystery of that spirit became a grave challenge for Amailoss and the many races in the region....''

''A naga campaign, involving elves, orcs, saurians, turtle-like races, and some monsters.''

'''Author:''' SkyOne

'''Status:''' Complete

'''Length:''' 16 playable, 2 dialog scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon

'''Faction/Era:''' Default with additions. You play a custom naga faction and carapaces (a turtle-like race).

'''[http://units.wesnoth.org/1.10/Return_of_the_Monster/en_US/Return_of_the_Monster.html Custom units]'''

'''Version:''' 0.7.1

'''Required Wesnoth version:''' 1.10.x

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36438

=== Return to Noelren ===

'''Status:''' Complete.

'''Length:''' 26 scenarios + 7 cut scenes

'''Author:''' Pyrophorus

'''Description:''' ''A story in the first Dark Age of Wesnoth. See how various heroes stick together to shun the threat of black magics, restore the secret kingdom of Noelren and install Garard I on the throne of Wesnoth. This campaign features complex scenarios, unusual objectives and units, emphasizing more on story and adventures than hardcore fighting.''

'''Version: ''' 0.7.6

'''Requirements:''' BfW 1.10 (not tested on 1.11)

'''Difficulty:''' Easy, unbalanced

'''Style:''' Skirmish, RPG, Large Battle, Simulation

'''Faction/Era:''' Default + custom units

'''[http://units.wesnoth.org/1.10/ReturnToNoelren/en_US/ReturnToNoelren.html Custom Units]'''

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34685#p501026

'''Note:''' (Adamant14) I never saw so much fantastic and new ideas in one single UMC, wow!

=== Return to Ruins ===

''The humble farmers of Vertegris are summoned by Erik the General of Weldyn to put an end to an orcish raiding party. If they knew what would befall their former home... They never would have left. This is a relatively short campaign with 8 scenarios, It is still undergoing changes.''

'''Author:''' Jeff Stevens (Ulfsark)

'''Composer:''' Paul Fredericks (paulfredericksmusic.com)

'''Status:''' Complete

'''Length:''' 7 scenarios + 1 dialogue-only

'''Difficulty:''' Easy,Normal,Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default,(Loyalists, Outlaws)

'''Version:''' 0.5.1

'''Required Wesnoth version:''' 1.10.x

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37790&sid=9059f18497cda1219f42a626544d0ffd&p=540646#p540646

'''Note:''' (Adamant14) You play a short campaign with just a few units. Playable in a few hours, nevertheless it is fun to play.

=== Salt Wars ===

''Introductory campaign for the Era of Four Moons.''

''As an officer of one of the Sea States you must defend your organization from aggressive rivals.''

'''Author:''' Velensk

'''Maintainer:''' Lavender

'''Status:''' Complete

'''Length:''' 5 scenarios

'''Difficulty:''' Easy

'''Style:''' Skirmish

'''Faction/Era:''' Era of Four Moons, Sea States

'''Version:''' 0.2.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=31498

=== Saving Elensefar ===

''Meneldur, elvish mariner of Elensefar, is driven to sea by the same orcs who attacked the city. He must gather an army willing to fight for him to regain Elensefar, his adopted homeland.''

'''Author:''' Turin

'''Maintainer:''' trewe

'''Status:''' Finished

'''Length:''' 1 year (around 12 scenarios)

'''Difficulty:''' Normal

'''Style:''' Skirmish, RPG, Simulation

'''Version:''' 1.5.2

'''Faction:''' Default Era

'''Forum:''' http://wesnoth.org/forum/viewtopic.php?t=3072&start=0

'''Wiki:''' [[SeafaringCampaign]]

'''Note:''' Labeled as Expert, recruit list changes in all scenarios.

=== Shameless Crossover Excuse ===

''Fugitive dark sorcerer Gwiti Ha'atel discovers he has the power to mess with Wesnoth's continuity. His quest for revenge on the NPCs who have used his portraits will lead him through perils untold and in-jokes unnumbered, but shall pale before the horror he finds at his quest's end.''

'''Author:''' Orcish Shyde, Mountain_King

'''Status:''' Complete

'''Length:''' 9 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Version:''' 1.1.0

'''Faction:''' Undead

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=32016&start=15

=== Swamplings ===

''Banished by Yushnak the Ponderer, a tribe of lowly swamp goblins endure in the deadly mire of Pogo Bog. Four centuries before the founding of Wesnoth, this is the story of the goblins' struggle against the intrigues and betrayals of the greater races, and the rise of the first wolf rider.''

'''Author:''' John Rawlins (boru)

'''Status:''' Complete

'''Length:''' 14 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Version:''' 1.1.7n

'''Faction:''' Goblins

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=29784

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Swamplings Players Review]'''

=== Talentless Mage===

''Humorous and silly campaign about mage apprentice who has managed to learn only one simple spell in thirty years.''

'''Author:''' Wonderboy

'''Status:''' Complete

'''Length:''' 11 playable scenarios + 3 dialogue scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Noob Faction

'''Version:''' 1.1.0

'''Forum:''' http://wesnoth.org/forum/viewtopic.php?f=8&t=27608]

'''[http://wiki.wesnoth.org/index.php?title=Guide_to_UMC_Campaigns/Players_Reviews&action=submit#Talentless_Mage Players Review]'''

=== The Dark Alliance===

''Prince Terhar lived two years with elves. Little did he expect what would happen when he returned back to Weldyn.''

'''Author:''' Wonderboy

'''Status:''' Complete

'''Length:''' 11 or 10 playable scenarios depending on the branch you take (+ 5 dialogue scenarios)

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default: Recruit list changes in almost every scenario

'''Version:''' 1.0.3"

'''Forum:''' http://wesnoth.org/forum/viewtopic.php?f=8&t=26924

=== The Dark Hordes ===

'''Status:''' Incomplete/WIP

'''Length:''' 11/?

'''Author:''' Circon

'''Maintainer:''' Various

'''Description:''' Lead fugitive dark sorcerer Gwiti Ha’atel to mastery of the undead hordes.

'''Version: '''

'''Requirements:'''

'''Difficulty:'''

'''Style:''' Skirmish

'''Faction/Era:''' Default undead

'''[http://units.wesnoth.org/1.10/The_Dark_Hordes/en_US/The_Dark_Hordes_1.html Custom Units]'''

'''Walkthrough:''' [[TheDarkHordes]]

'''Forum:''' [[http://forums.wesnoth.org/viewtopic.php?f=8&t=16576&]]

=== The Devil's Flute ===

'''Status:''' Complete, unmaintained

'''Length:''' 10 scenarios

'''Author:''' lipk

'''Description:''' Creona, the well-known assassin, gets a strange job from a strange person. So, in fact, it's no surprise that things take a strange turn...

'''Version:''' 0.1.4c

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish, Minigames

'''Faction/Era:''' Outlaws

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36044

=== The Earth's Gut ===

''The year is 515YW. You are the young dwarven leader Hamel. Your tribe in the caves of Knalga is under pressure from its enemies, and resources are growing scarce. In order to forge the weapons required to resist your enemies, you must set forth and collect what ores and minerals remain.''

'''Author:''' Anonymissimus

'''Maintainer:''' Anonymissimus

'''Status:''' WIP, story is unfinished (I didn't add any scenario since long, but that doesn't mean nothing is added to the campaign. My addons tend to be in good shape and bug-free which means also WIP as I'm updating it since 1.4 days.)

'''Length:''' 23 scenarios, 5 of which are cutscene only, some others have changing objectives

'''Difficulty:''' Normal

'''Style:''' Dungeon, Skirmish

'''Faction/Era:''' Default, dwarves, woses, mages, a few custom units

'''[http://units.wesnoth.org/1.10/The_Earths_Gut/en_US/the_earths_gut.html Custom units]'''

'''Version:''' 0.2.14

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=26800

'''Note:''' This campaign is a "Dwarvish dungeon crawler" (It currently contains about as many surface scenarios as underground though.) and is intended to be challenging for experienced players on hard whilst suitably easy on easy. I develop the campaign with the wesnoth development version and I advise to play with that, but it is intended to work almost equally well with the stable wesnoth version (except for features only available in the wesnoth development version).

=== The Epic of Vaniyera ===

''The expansionist Lavinian Legion, led by the Imperator himself, has invaded the northern forests of the Sidhe, or Wild Elves. It is up to Leithan the Thunderblade and his advisor Vaniyera to push its armies back where they came from...''

'''Author:''' oreb, turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 6 scenarios

'''Difficulty:''' Hard (Don't be fooled by "novice level" in the campaign description, this one is very hard.)

'''Note:''' (Maintainer) Working on this issue, the next release (due at the end of November, hah!) should bring easy difficulty back to the level of a reasonable introduction to the IE, while the hard difficulty will also become slightly easier. With any luck, this will be the last release before version 1.0 of the campaign].

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Sidhe.

'''Version:''' 0.9.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=19490

=== The Fall of Wesnoth ===

''As the beloved human empire of Wesnoth becomes lazy and arrogant in its peaceful state of happiness, Emperor Dantair demands the creation of another sun in a bid to destroy all evil. Or is it all for a different purpose? A man named Alitar sees it that way, and now he must survive the most evil inhabited lands if he is to stop chaos from rising, and Wesnoth from falling... This is the story of The Fall of Wesnoth.''

'''Author:''' Pewskeepski

'''Status:''' 1st part complete, 2nd WIP.

'''Length:''' 10 playable scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Outlaws

'''[http://units.wesnoth.org/1.10/The_Fall_of_Wesnoth/en_US/The_Fall_of_Wesnoth-1.html Custom units]'''

'''Version:''' 1.0.8

=== The Founding of Borstep ===

''The chieftain of your tribe has become decadent and weak. Take over, and lead your people to a better home--whether it is already occupied or not. The Northlands in year 9W are a barbaric place, but anyone who stands in your way will learn the power of orcs!''

'''Author:''' Beetlenaut

'''Status:''' Complete

'''Length:''' 10 and 1 dialogue only

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default, Northerners

'''[http://units.wesnoth.org/1.10/The_Founding_of_Borstep/en_US/The_Founding_of_Borstep.html Custom units]'''

'''Version:''' 1.1.1b

'''Note:''' (Kanzil) I find the protagonist hard to sympathise with. Also, most scenarios contain interesting twists. For example, in one, each time you killed a boar it gives you extra health.

'''Note:''' (beetlenaut--author) In most Orcish campaigns the leader is heroic or just wants peace. Krag-Ubor wants plunder and battle like all enemy Orcs in other campaigns. I '''hope''' you don't sympathize too strongly, but I don't think you need to in order to enjoy the game play.

=== The Library of Kratemaqht ===

''An ancient story from the old continent.''

'''Author:''' Rich Marinaccio (cephalo)

'''Status:''' Complete

'''Length:''' 17 scenarios

'''Difficulty:''' Unbalanced (some scenarios are Easy - some rather Hard)

'''Style:''' Skirmish, RPG

'''Faction/Era:''' Loyalists and custom units.

'''[http://units.wesnoth.org/1.10/Library_Of_Kratemaqht/en_US/The_Library_Of_Kratemaqht.html Custom units]'''

'''Version:''' 1.0.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37798

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#The_Library_of_Kratemaqht Players Review]'''

'''Notes:''' (Adamant14) This campaign has a thought-out story, shows a great love for detail;
It includes a great custom Dragon, some brilliant custom images (fire, burning houses, burning forest) that makes the scenery / maps look very nice.

=== The Roar of the Woses ===

''When the construction of a dam threatens the existence of her home, Kylix is forced on a journey to stop it.''

'''Author:''' Alarantalara

'''Status:''' Finished

'''Length:''' 10-11 scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default with Additions (primarily Saurians, Nagas, Woses)

'''Version:''' 1.2.7

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=29830

'''Note:''' (author) Potentially unbalanced on Hard difficulty due to experiments with non-standard ways to increase difficulty. This issue does not exist on the lower difficulty levels.

=== The Three Elves ===

''Three elves have just begun their adventure in the northern swampland. Will they become heroes or will they be responsible for another undead expansion?''

'''Author:''' Stanislav Hoferek

'''Maintainer:''' trewe

'''Version:''' 0.9

'''Status:''' Complete

'''Difficulty:''' Easy

'''Length:''' 8 scenarios + 2 dialogue

'''Style:''' Skirmish

'''Faction:''' Default (Elves)

'''Forum:''' (does it have one?)

=== The Sojournings of Grog ===

''Grog (as starred in Under the Burning Suns) goes home.''

'''Author:''' Peter Christopher, Thomas Hockings

'''Maintainer:''' Elvish_Hunter

'''Status:''' Finished

'''Length:''' 18 playable scenarios in 2 parts

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon, Large Battle

'''[http://units.wesnoth.org/1.10/The_Sojournings_of_Grog/en_US/The_Sojournings_of_Grog.html Custom units]'''

'''Faction/Era:''' Default. Most of the time you play trolls and some desert elves accompanying Grog.

'''Version:''' 3.0.1

=== The Unstoppable Legion ===

''Horseback campaign. The kingdom of Suveran, far away from Wesnoth, is under attack. Only Deuterus, a Great Druid, knows their weakness and only Viktor, a young noble, dares go on the quest to stop them.''

'''Author:''' Chris Neville-Smith (Chris NS)

'''Maintainer:''' Chris Neville-Smith (Chris NS)

'''Status:''' WIP

'''Length:''' Currently 15 playable sceanrios, including a fork of three paths near the beginning, and another fork of two paths later on.

'''Difficulty:''' Normal

'''Style:''' Mainly Skirmish

'''[http://units.wesnoth.org/1.10/The_Unstoppable_Legion/en_US/The_Unstoppable_Legion.html Custom units]'''

'''Faction/Era:''' Play mounted units, including expanded Cavalryman line, and completely new Bowrider line. Joined later by Dwarves. Main enemies are the dark fighters and dark cultists.

'''Version:''' 0.8.7

=== The White Troll ===

''The story of a white troll whelp with strange magic powers, who is raised in an elvish village.''

'''Author:''' Wesnoth Italian Forum

'''Status:''' Complete

'''Length:''' 8 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default: you play with elves and trolls. Also features custom units with special advancements and abilities.

'''[http://units.wesnoth.org/1.10/White_Troll/en_US/white_troll.html Custom Units]'''

'''Version:''' 0.7.5

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=38828

=== To Lands Unknown ===

''This is the story of Mehir, the Summoner, and his journey to lands unknown.''

'''Author:''' inferno8

'''Status:''' Complete

'''Length:''' 20 scenarios, 4 dialogue only

'''Difficulty:''' Intermediate (Era of Magic)

'''Style''': Skirmish, Dungeon

'''Era:''' Era of Magic

'''Version:''' 1.6.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=31799

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#To_Lands_Unknown Players Review]'''

=== Unlikely Alliance ===

''Play as the members of an alliance between the elves, drakes, and undead after the Fall of Wesnoth.''

'''Author:''' Creativity

'''Status:''' Broken ( Abandoned )

'''Length:''' 2 broken scenarios

'''Difficulty:''' Unbalanced

'''Style:''' -

'''Faction/Era:''' -

'''Version:''' 0.1

'''Forum:''' -

'''Note:''' (Adamant14) Did not work at all. Seems abandoned.

=== Up from Slavery ===

''The Orcei are captives in the imperial city of Lavinium, gladiators performing for the emperor Optus Maximus. All it will take, however, is one orc to lead his people to freedom. The Samnis called Sparxus may be that orc.''

'''Author:''' turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 7 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish, Arena (= No recruit, small group gladiator fights)

'''Faction/Era:''' Imperial Era, Orcei Gladiatores

'''Version:''' 0.6.0

'''Note:''' (Maintainer) At some point, I am intending to completely re-work this campaign to be a multi-player campaign, with one side led by Sparxus and one by Gravirivus. If anyone would like to take this on or has ideas for how to accomplish this, let us know. Nevertheless, its playable as a single player campaign now with some nice ideas that could be developed further.]

=== Warmaster ===

''One day the scout of your king brings a mysterious little stone, called Zrai-Stone, back from one of his trips. Soon that stone causes a lot of trouble...''

'''Author:''' Conkinator

'''Maintainer:''' trewe

'''Version:''' 1.3.5

'''Status:''' Finished

'''Length:''' 16 battle + 2 bonus + 1 epilogue scenarios

'''Difficulty:''' Hard

'''Faction:''' Default (loyalists)

'''Style:''' Skirmish, Survival

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=15527

=== Way of Dragon ===

''The story of what might happen if a person against his will transform into a dragon...''

'''Author:''' DrakeDragon

'''Status:''' Complete

'''Length:''' 7 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish/RPG

'''Faction/Era:''' Default Loyalists

'''Version:''' 1.2.0

'''Forum:''' [http://forums.wesnoth.org/viewtopic.php?f=8&t=37876 Wesnoth Forum] [http://uporoom.ru/index.php/topic,179.0.html Russian Forum]

'''Note:''' (Adamant14) Promising short campaign, you play with just a few units.

== Battle for Wesnoth 1.11.x - development ==

''Campaigns available in the 1.11.x development version.''

''Please note: Battle for Wesnoth 1.11.0 features a bug that messes up the selection of difficulty levels.''

=== Antar, Son of Rheor ===

''This is the story about a young Lord and his first mission; sent by his father the young Lord Antar has to relieve his neighbours; he has to convince the Elves and Dwarves to ally him; he has to fight against hordes of Orcs and Endless Undead; and finally he has to defeat Mal Kazur, the mastermind who is behind all the evil.''

'''Author:''' Adamant14

'''Status:''' WIP

'''Length:''' 9 playable scenarios / 1 cutscene

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Loyalists and Elves (feat. fencer as main hero + various allies)

'''Version:''' 0.9.9

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36075

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Antar.2C_Son_of_Rheor Players Review]'''

'''Note:''' (Adamant14) The campaign did not work with BfW version 1.11.0, or BfW version 1.11.1, so please use BfW version 1.11.2 or later!

=== A Song of Fire ===

''''''Part I: The Last War''' - In a long-forgotten era, at the heart of the Great Continent, an ancestral evil is awakened, threatening to destroy the whole world. Follow young Myra in the war that will alter the future of Irdya and its peoples forever.''

''''''Part II: Towards the Rising Sun''' - After the vicious Last War, Myra has become the new leader of Aragwaithi and Windsong alike. Albeit young and shaken by many losses, she must steel herself to lead her people through the vast and hostile Hannuk Steppes. However, her journey will take them all farther than in their wildest dreams. Furthermore, Myra must deal with the evil influence of the mysterious red gem she found after the last battle.''

''''''Part III: Raging Skies''' - The refugees have finally found a new home: families are built, allies are made and, for the first time in years, Myra and her friends know peace. However, when everything seems normal, ambition and thirst for power cause the break out of a continental war. And, amidst this new storm, an old foe rises agan, more powerful than ever. Witness the end of the song of Irdya's first great heroine.''

'''Author:''' revansurik

'''Status:''' Complete

'''Length:''' 36 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish, Large Battle

'''Faction/Era:''' Default+War of Legends

'''Version:''' 0.3.4

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=38210

=== Bad Moon Rising ===

''An expedition to gather treasure from the cold north sets off compounding disaster.''

'''Author:''' Doofus-01

'''Status:''' Finished

'''Length:''' 20 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Archaic Era

'''Version:''' 1.5.8

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=31348

=== Birth of a Lich ===

''This is the life story of the dreaded lich Malifor, his struggle as a mage outcast, the orcish conquest of the northlands and his transformation to quench the thirst for revenge''

'''Author:''' chak_abhi

'''Status:''' Finished

'''Length:''' 12 playable scenarios / 2 dialogue only

'''Difficulty:''' Normal

'''Style:''' Skirmish, Large Battle, Dungeon

'''Faction/Era:''' Human outlaws, dwarves, undead

'''[http://units.wesnoth.org/1.10/Birth_of_a_Lich/en_US/Birth_of_a_Lich.html Custom Units]

'''Version:''' 1.0.3

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37057

=== Coming of the Storm ===

''A new recruit joins the imperial army, eager to change the world and see combat. Little does he realise just how much action he will get and where his journey will take him. ''

'''Author:''' TrashMan

'''Status:''' WIP

'''Length:''' 26 playable scenarios / 4 dialogue only

'''Difficulty:''' Normal

'''Style:''' Skirmish, Large Battle, Dungeon

'''Faction/Era:''' Default

'''Version:''' 1.2.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23361

=== Legend of Far North ===

''The tale of the legendary Black Eye Karun,depicting his rise to power, his successes and his brutal assassination.'

'''Author:''' chak_abhi

'''Status:''' Finished

'''Length:''' 16 playable scenarios / 1 dialogue only,1 cutscene

'''Difficulty:''' Normal

'''Style:''' Skirmish, Large Battle

'''Faction/Era:''' Orcs, Trolls, Saurians, Nagas

'''[http://units.wesnoth.org/1.10/Legend_of_Far_North/en_US/Legend_of_Far_North.html Custom Units]'''

'''Version:''' 1.0.2

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34769

=== Legend of the Invincibles ===

'''''Part I: Shrouded in Darkness''' (5 chapters, 90 scenarios) - A pair of heroes, after stopping an orcish thread, are outcast into caves, where they have no other choice than to become liches in order to survive. They preserved their original appearance and moral principles, and fight in various skirmishes against evil (although using evil methods sometimes), until the Fall, when they are buried alive under the ashes of the third sun.''

'''''Part II: Into the Light''' (4 chapters, 96 scenarios at the moment) - Long after the Fall, the lich heroes awaken. Searching for more power, they manage to resurrect themselves as living beings, but this time more powerful and ridden of the evil within. But the evil from inside them did not cease to exist, and started a campaign to conquer the world. Stopping the campaign caused an even worse disaster...''

'''Author:''' Dugi

'''Status:''' WiP (but Part I might be considered complete)

'''Length:''' 185 (+7 talk-only) scenarios at the moment

'''Difficulty:''' Normal

'''Style:''' mostly Skirmish and Dungeon (all other styles are present as well, but less frequently)

'''Faction/Era:''' Elves, Loyalists, Undead, Dwarves; but they advance past their usual maximum level

'''Version:''' 2.5.0

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Legends_of_the_Invincibles Players Review]'''

'''Note:''' The most unique feature of this campaign is its RPG-like unit development system, enemies drop items units can use, leaders are stronger than most usual units and all units get AMLA (after maximum level advancement) after reaching their maximum level (that is also increased by a load of additional level 4 units).

=== Rebellion in the North ===

''A great orcish uprising tends to destabilise the Northlands. As the future Lord Protector of the Northern Alliance you have to crush the rebellion and establish peace again."

'''Author:''' chak_abhi

'''Status:''' Finished

'''Length:''' 24 playable scenarios / 3 dialogue only,2 cutscenes

'''Difficulty:''' Normal

'''Style:''' Skirmish, Large Battle

'''Faction/Era:''' Loyalists, Dwarves, Gryphons, Merfolk

'''Version:''' 1.1.12

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=33059

=== Ruthless ===

''A bard (an aging criminal) is walking in wasteland. Nothing but two hands in his pockets, and nothing but stones around. Suddenly he sees a knight on errand--a dangerous opponent, especially in broad daylight. The two strangers are soon sitting by the campfire, and the bard is telling a story.
(Beginner level, 10+ fights).''

'''Author:''' homunculus

'''Status:''' Finished

'''Length:''' 12 playable scenarios + 5 cutscene scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default (Orcs)

'''Version:''' 1.0.4

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37874

'''Note:''' (Adamant14) Recommendable campaign, with smart unusual ideas and a good detailed story.
You fight with few units on small but perfect maps. About the difficulty: The author describes his campaign as 'beginner level', but for me the difficulty is rather NORMAL than EASY.

== [[Guide_to_UMC_Campaigns/Players_Reviews|Player Reviews]] ==

[[Category:Campaigns|*]]

Guide to UMC Content

2013-06-11T16:53:36Z

Anonymissimus: /* The Earth's Gut */ update and enhance my campaign description

''This is a guide to the current (1.10.x/1.11.x) UMC campaigns for players. It aims to provide all the information not only about the story, but also about completion, difficulty and playing style of the campaign. See also [[Guide_to_UMC_Campaigns/Players_Reviews|Players Reviews]], as well as http://forums.wesnoth.org/viewtopic.php?f=8&t=37476 for further information and http://forums.wesnoth.org/viewtopic.php?f=8&t=36733 (for currently non-available UMC-content). Please edit, it is a wiki.''

=== Blueprint ===

'''Status:'''
* Broken = Does not work at all
* Incomplete = Partially written, no progress
* WIP = Partially written, progress
* Complete = Completely written, but buggy as well as potential balance issues.
* Finished = Completely written, minimal to no bugs, slight balance issues possible.

'''Length:'''

'''Author:'''

'''Maintainer:''' if not maintained by the author anymore.

'''Description:'''

'''Version: '''

'''Requirements:'''

'''Difficulty:'''

Please note: Often campaigns introducing new mechanics are listed as expert level on the add-on server, here difficulty means the raw difficulty after the mechanics are understood.

* Unbalanced = If you can't beat the hard mode, it isn't necessarily unbalanced, but if the difficulty changes erraticly from one scenario to the next and only people using the debug mode have seen the final, then it is.
* Easy
* Normal
* Hard

'''Style:'''

Please note: Many campaigns will feature more than one style. Please list the most significant ones.

* Skirmish = small to medium sized armies, your standard Wesnoth gameplay
* Dungeon = long and narrow tunnels (not every underground scenario is a dungeon, a dungeon isn't necessarily underground)
* RPG = role playing game elements such as talking with non-player-characters, item collection, dependency on a party of very few adventurers without or limited recruits
* Survival = being exposed to changing, spawning enemies while remaining on the same map
* Large Battle = large number of units on the battlefield, sizely maps
* Simulation = campaigns feat. terrain modification, alternative resources
* Boss battle = the challenge is to defeat a single powerful enemy unit
* Minigames = there are puzzles and minigames in the campaign that significantly differ from standard Wesnoth gameplay

'''Faction/Era:'''

* Era for the whole campaign and more specifically the faction or unit composition you field.

'''Custom units:'''

* Link to the unit tree for cases that don't feel sufficiently described by Faction / Era entry.

'''Forum:'''

* Links to the feedback and development threads at forums.wesnoth.org

== Battle for Wesnoth 1.10.x - stable ==

''Campaigns available in the 1.10.x stable version.''

=== After the Storm ===

''Follow the journey of Elynia and her band following the events of Invasion from the Unknown''

'''Author:''' shadowmaster/ShikadiLord

'''Status:''' Finished

'''Length:''' 3 episodes of approximately 12 scenarios each, some of which are multi-part

'''Difficulty:''' Medium-hard

'''Style:''' Skirmish, Boss Battle, Dungeon

'''Faction/Era:''' Many custom units

'''Version:''' 0.9.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=32091

'''Note:''' (vultraz) Long, very enjoyable campaign with great story.

=== Aldur The Great ===

''This is a story about Aldur the Great.''

'''Author:''' pintercsabi

'''Status:''' Complete, but unbalanced

'''Length:''' 5 playable scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default

'''Version:''' 1.2.2

'''Forum:''' -

'''Note:''' (Adamant14) Short unbalanced campaign, maybe abandoned. You fight with Peasants, Ruffians and Woodsman against Orcs

=== Alfhelm the Wise ===

''This is the tale of Alfhelm, called by some the Wise, son of Alfric Conqueror. This is the tale of his victories over his enemies, and his rise to power in the clans of Marauderdom. This is the tale of his journey south and his destruction of the Lavinian Empire. And this is the tale of his demise in the dark forests far to the east of his homeland.''

'''Author:''' turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 15 gameplay scenarios

'''Difficulty:''' Moderate

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Marauders.

'''Version:''' 0.6.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=17144

'''Note:''' (Maintainer) Though this campaign is complete and playable the whole way through, the code is four years old and pretty buggy. If you notice any errors while playing, please let me know and I'll incorporate the fixes into my next revision as soon as possible.]

=== A New Order ===

'''Author:''' szopen

'''Status:''' Finished.

'''Length:''' 45 scenarios.

'''Description:''' The old kingdom of Wesnoth has fallen before barbarian hordes. The occupying barbarians are on the brink of civil war, the seeds of Wesnothian rebellion are kept alive by old legends, while bandits and Khalifate mercenaries roam the land. Can Gawen Hagarthen unite these disparate factions against a common foe?
Note: This campaign contains mature themes, some of which may be unsuitable for children.

'''Version: ''' 1.2.15

'''Requirements:''' Requires BfW 1.10. In addition, you have to install Era Khalifate add-on; the Akladian Music package is optional

'''Difficulty:''' Normal

'''Style:''' Skirmish, Large Battle

'''Faction/Era:''' Akladians, Khalifate

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=6486

'''Note:''' (Pyrophorus) Certainly one of the most mature and well designed campaign in add-ons. A must.

=== Antar, Son of Rheor ===

''This is the story about a young Lord and his first mission; sent by his father the young Lord Antar has to relieve his neighbours; he has to convince the Elves and Dwarves to ally him; he has to fight against hordes of Orcs and Endless Undead; and finally he has to defeat Mal Kazur, the mastermind who is behind all the evil.''

'''Author:''' Adamant14

'''Status:''' WIP

'''Length:''' 9 playable scenarios / 1 cutscene

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Loyalists and Elves (feat. fencer as main hero + various allies)

'''Version:''' 0.9.9

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36075

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Antar.2C_Son_of_Rheor Players Review]'''

=== A Story of the Northlands ===

''A story of life and death in a remote village of the Northlands. Your village has been overrun by an orcish raid. You fight for its freedom while you wait for help to arrive.''

'''Author:''' zepko

'''Status:''' Complete

'''Length:''' 10 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default + additions: you play with a custom faction of outlaws and with a custom party of loyalist knights.

'''[http://units.wesnoth.org/1.10/A_Story_of_the_Northlands/en_US/A_Story_of_the_Northlands.html Custom Units]'''

'''Version:''' 1.0.0

=== A Vision Blinded ===

''Defend the northern forest against what appeared like a routine orcish raid, and unravel the greater conspiracies that lie below its waves.''

'''Author:''' LemonTea

'''Maintainer:''' AxalaraFlame

'''Status:''' Complete

'''Length:''' 13 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves (+ Trolls, Outlaws)

'''[http://units.wesnoth.org/1.10/A_Vision_Blinded/en_US/A_Vision_Blinded.html Custom units]'''

'''Version:''' 0.6.6

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23463&hilit=a+vision+blinded

=== Bad Moon Rising ===

''An expedition to gather treasure from the cold north sets off compounding disaster.''

'''Author:''' Doofus-01

'''Status:''' Finished

'''Length:''' 20 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Archaic Era

'''Version:''' 1.4.4.a

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=31348

=== Battle Against Time===

''Rescue fellow orcish warchief before he is executed. (This is not a normal campaign. It is experiment with carryover system. You will start with defined number of turns and gold. You will only have that many turns to play through the whole campaign. There is no finish bonus and gold carryover is always 100%.)''

'''Author:''' Wonderboy

'''Status:''' Complete

'''Length:''' 4 playable scenarios + 1 prologue scenario

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default: Orcs

'''Version:''' 1.0.0

'''Forum:''' http://wesnoth.org/forum/viewtopic.php?f=8&t=27319

=== Besieged Druids ===

''A elvish school for druids comes under attack by goblins. It seems more than just a routine raid; is there something more sinister behind this attack? - In Beseiged Druids, you control Eärendil, the surviving teacher at the school, and the many and varied initiates. Not all of these are ordinary students; many have been experimenting with other forms of magic, while others are simply overachievers in some area of study. Unfortunately, they are not especially good at combat, at least initially. Together with a very small contingent of surviving guards, it is up to these students to save the island of Aleron from disaster.''

'''Author:''' Celtic Minstrel

'''Status:''' Complete

'''Length:''' 9 scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''[http://units.wesnoth.org/1.10/DruidSiege/en_US/celmin-druid-siege.html Custom units]'''

'''Version:''' 1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37342

=== Birth of a Lich ===

''This is the life story of the dreaded lich Malifor, his struggle as a mage outcast, the orcish conquest of the northlands and his transformation to quench the thirst for revenge''

'''Author:''' chak_abhi

'''Status:''' Finished

'''Length:''' 12 playable scenarios / 2 dialogue only

'''Difficulty:''' Normal

'''Style:''' Skirmish, Large Battle, Dungeon

'''Faction/Era:''' Human outlaws, dwarves, undead

'''[http://units.wesnoth.org/1.10/Birth_of_a_Lich/en_US/Birth_of_a_Lich.html Custom Units]

'''Version:''' 1.0.3

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37057

=== Bitter Revenge===

''Amidst the strife and turmoil of the first Dark Age of Wesnoth, a time of transient monarchies and conspiracies against the Crown, the boy Darith witnesses the murder of his father by a general of Wesnoth. Follow Darith's quest for retribution in this treacherous tale of betrayal, deceit, love, remorse, and vengeance.''

'''Author:''' Wonderboy

'''Status:''' Complete

'''Length:''' 11 playable scenarios + 4 dialogue only

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default (mostly outlaws and undead, custom units)

'''Version:''' 1.1.0

'''Forum:''' http://wesnoth.org/forum/viewtopic.php?f=8&t=26699

=== Cavanagh The Conqueror ===

''This is the tale of Cavanagh Orc-Foundling, who was blessed by the gods to conquer and unite all of the Great Continent. Orcs and elves, gods and men, queens and sorcerers populate this epic tale of revenge and redemption.''

'''Author:''' TheEmptyLord (Programming, Map-making, Editing), Scott_Free(Story)

'''Status:''' WIP

'''Length:''' 10 Playable Scenarios so far

'''Difficulty:''' Normal

'''Style:''' Skirmish, limited RPG, limited Large Battle

'''Faction/Era:''' Default (Units from Northerners, Outlaws, Loyalists as well as other factions interspersed. Several custom units.)

'''Version:''' 0.1.2

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=35927

=== Cities of the Frontier ===

''Settle a new town in the wilds north of the Great River.''

''This campaign makes several changes to the standard Wesnoth game mechanics, and focuses on city-building and gold management.''

'''Author:''' esci

'''Status:''' Complete

'''Length:''' Not fixed, approximately 6-10 seasons of 36 turns each

'''Difficulty:''' Normal

'''Style:''' Simulation, Survival

'''Faction/Era:''' Default, Loyalist

'''[http://units.wesnoth.org/1.10/Cities_of_the_Frontier/en_US/Cities_of_the_Frontier.html Custom units]'''

'''Version:''' 0.5.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36004

=== Considerate Dead ===

''As the wind goes on and on, people discover necromancer aren't always bad. Made by tribes45 - No scenarios are done, 4 playable out of ??.''

'''Author:''' tribes45 aka tribes55

'''Status:''' Incomplete, unbalanced, abandoned

'''Length:''' 5 scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default

'''Version:''' .009

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36522

=== Count Kromire ===

''You are the blood son of a vampire lord, however when the might of the celestial crusades comes knocking, and your father is slain, you flee your lands. However you intend to return, to restore the lands of Kromire to the Kromires, to avenge your father, and most importantly, to make sure that no celestial ever dares come into your mountains again.''

'''Author:''' Velensk

'''Maintainer:''' currently none

'''Status:''' Complete

'''Length:''' 9 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Era of Myths, Vampires

'''Version:''' 1.3.2

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=21560

=== Elvish Dynasty RPG ===

''You are the new ruler of an elvish kingdom! Can you lead your people to glory? This campaign is highly randomized so it will be different every time you play!''

''Sequel to Ooze Mini-Campaign''

'''Author:''' spencelack

'''Maintainer:''' Wesbane

'''Status:''' Complete

'''Length:''' 10 years, in each year choice between dialogue and fighting scenario (selected out of a large pool of possible scenarios)

'''Difficulty:''' Normal

'''Style:''' RPG, Skirmish

'''Faction/Era:''' Default, Elves

'''Version:''' 0.9.9b

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=28627

=== Fall of Silvium ===

''You are Caius Regilius, Tribune of the province of Silvia, located in the northmost reaches of the Lavinian Empire at the height of its power. But the Empire has overextended itself, The city of Silvium lies seperated from the rest of the Empire by the mountains of Arendia, and is sandwiched between the Marauders and the Sidhe... war is inevitable, and the province of Silvia will almost certainly fall.''

'''Author:''' turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 8 scenarios

'''Difficulty:''' Medium

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Lavinian Legion.

'''Version:''' 0.6

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=31&t=24356

'''Note:''' The final level of this campaign is not supposed to be winnable. It's a final blaze of glory and chance to use all your high-powered units, but to 'win' the campaign, you must lose...the ending is similar to a certain mainline campaign, but predates it.

=== Fate of a Princess ===

''Part I: Baldres, a notorious robber baron, flees Wesnoth with his followers and sets off into the northlands to evade the king's justice. The baron's deeds and misdeeds are to change the balance of power between orcs and non-orcs throughout the northlands, and will carry consequences long after his eventual death.''

''Part II: The Greenwood elves face a crisis which demands the return of the queen's estranged half-elven half-sister, Baldres' daughter. Two brave young elves must make a perilous journey to find her and bring her back to her former home. If they fail, the whole northlands will be engulfed in war with the resurgent orcs...''

'''Author:''' SkyOne, mich, simonsmith

'''Status:''' Finished

'''Length:''' 26-29 scenarios (some dialogue-only), 2 parts

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon

'''Faction/Era:''' Default with additions. You play two different, unique cross-faction combinations in each part.

'''[http://units.wesnoth.org/1.10/Fate_of_a_Princess/en_US/Fate_of_a_Princess.html Custom units]'''

'''Version:''' 0.9.17

'''Required Wesnoth version:''' 1.9.12 or later

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=26327

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Fate_of_a_princess Players Review]'''

=== Forgotten Kingdom ===

''Help Orlog, a troll chieftan, lead his people to safety in the underground and discover an ancient power long forgotten.''

'''Author:''' Limabean

'''Maintainer:''' Chrysophylax

'''Status:''' Incomplete ( but all scenarios playable and balanced )

'''Length:''' 9 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Goblins, Trolls

'''[http://units.wesnoth.org/1.10/Forgotten_Kingdom/en_US/Forgotten_Kingdom.html Custom units]'''

'''Version:''' 0.1.7

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23483

'''Note:''' (Adamant14) This campaign includes a custom Troll line. A good campaign, I hope Limabean and/or Chrysophylax will finish it.

=== Forward they Cried ===

''You are the leader of an advanced detachment that has been tasked with capturing a bridgehead while the main army prepares to attack. It should be a simple enough assignment.''

'''Author:''' Glowing Fish

'''Maintainer:''' Lord-Knightmare

'''Status:''' Finished

'''Length:''' 1 scenario ( rather a single scenario than a campaign )

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default Loyalists

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23656&p=350126&hilit=forward+they+cried#p350126

'''Version:''' 1.0.0

'''Note:''' (Adamant14) Only a single scenario, but a great scenario.
(UnwiseOwl) You wouldn't want to stop thinking for a turn, and it's good for the first few turns, but this one leaves me wanting more.

=== Galuldur's First Journey ===

''While the belligerence of orcs is nothing new, their intensifying attacks on a fledgling colony of elves in Pindir Forest begin to show signs of a deeper malice, forcing Galuldur, the young son of the colony's adventurous founder Galur, to venture out of his forest's friendly trees in search of help. His simple errand quickly turns into a frantic quest to unearth the roots of the mysterious evil threatening his people. As you lead him through unknown lands, Galuldur, forced to match wits with unexpected adversaries at nearly every turn in a desperate attempt to save his world, quickly learns that the world is neither a friendly nor a simple place.''

'''Author:''' mattsc

'''Status:''' Complete

'''Length:''' 8-9 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''[http://units.wesnoth.org/1.10/Galuldur/en_US/Galuldur.html Custom units]'''

'''Version:''' 1.1.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=31895

=== Grnk the Mighty ===

''All his life, puny little goblin Grnk the Frail had been dreaming about leaving the orcs and starting a better life. When he finally arrives in the human town of Shmaltupp, he realizes that the world is not as black and white as he had imagined. He also discovers that he is no ordinary goblin. Follow Grnk the Frail on his path to becoming Grnk the Mighty.''

'''Author:''' mattsc

'''Status:''' Part I complete

'''Length:''' 13 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish, RPG

'''Faction/Era:''' Default, changing (no standard army building gameplay)

'''[http://units.wesnoth.org/1.10/Grnk/en_US/Grnk.html Custom units]'''

'''Version:''' 1.0.5

'''Required Wesnoth version:''' 1.9.5 or later

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34970

=== Invasion from the Unknown ===

''Episode I - Seeking the Light: Long after the Fall, the last forest elves are forced to abandon their safe valley, and find themselves resorting to the dark means of necromancy in order to survive the perils and challenges of this new harsh world. May they finally free the Great Continent from its chaos, or perish in the foolish attempt of restoring peace and life to the lands.''

''Episode II - Armageddon: As the shadow of Chaos covers the entire continent, an assorted group of foolish heroes prepares a counter-attack to the Empire, with one unique goal in their minds: defeat the evil Emperor, whoever it is. Lead these courageous living and non-living warriors to victory, and rediscover lost secrets of the history.''

'''Author:''' shadowmaster

'''Maintainer:''' Espreon

'''Status:''' Finished

'''Length:''' 26 scenarios in two episodes

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon, Boss battle

'''Faction/Era:''' Unique. You play Elves and Undead throughout the campaign + in the 2nd part Northerners and Aragwaithi.

'''Version:''' 1.90.6

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Invasion_from_the_Unknown Players Review]'''

'''Note:''' (taptap) Despite its acknowledged flaws (generic hero, plot holes, deus ex machina moments, gameplay issues in the 2nd part) this is undoubtedly the most iconic campaign in UMC. It single-handedly redefines the elvish history and sketches a cosmology for the ages after the fall. With the Chaos empire and its various allies it introduces an era worth of factions to single-player play. At the same time it features some of the most beautiful maps in Wesnoth and stunning art on par with mainline campaigns.

=== Invasion of Eliador ===

''A peaceful island is about to be invaded by unknadd-ons foes travelling towards the eastern shore. It is up to a family of outlaws to warn the island's inhabitants before it's too late.''

'''Author:''' Sam M. (Genosuke)

'''Maintainer:''' trewe

'''Version:''' 1.0.4

'''Style:''' RPG, Skirmish, Puzzle

'''Length:''' 10 scenarios + epilogue

'''Difficulty:''' Easy

'''Status:''' Complete

'''Faction:''' Default (outlaws)

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=6556

'''Wiki:''' [[Invasion_of_Eliador]]

=== Langrisser Sample Campaign ===

''The Imperial Knights of the Rayguard Empire have disrupted the peace of the village that was Hein's hometown, seeking only a girl named Liana. Fight to rescue Liana.''

'''Author:''' Morath

'''Status:''' Finished

'''Length:''' 1 playable scenario

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''Version:''' 0.1.0.5

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36417&hilit=Langrisser

'''Wikipedia:''' [http://en.wikipedia.org/wiki/Langrisser What is Langrisser]

'''Note:''' (Adamant14) Single scenario, different from usual Wesnoth behaviour.

=== Legend of Far North ===

''The tale of the legendary Black Eye Karun,depicting his rise to power, his successes and his brutal assassination.'

'''Author:''' chak_abhi

'''Status:''' Finished

'''Length:''' 16 playable scenarios / 1 dialogue only,1 cutscene

'''Difficulty:''' Normal

'''Style:''' Skirmish, Large Battle

'''Faction/Era:''' Orcs, Trolls, Saurians, Nagas

'''[http://units.wesnoth.org/1.10/Legend_of_Far_North/en_US/Legend_of_Far_North.html Custom Units]'''

'''Version:''' 1.0.2

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34769

=== Legend of the Invincibles ===

'''''Part I: Shrouded in Darkness''' (5 chapters, 90 scenarios) - A pair of heroes, after stopping an orcish thread, are outcast into caves, where they have no other choice than to become liches in order to survive. They preserved their original appearance and moral principles, and fight in various skirmishes against evil (although using evil methods sometimes), until the Fall, when they are buried alive under the ashes of the third sun.''

'''''Part II: Into the Light''' (4 chapters, 96 scenarios at the moment) - Long after the Fall, the lich heroes awaken. Searching for more power, they manage to resurrect themselves as living beings, but this time more powerful and ridden of the evil within. But the evil from inside them did not cease to exist, and started a campaign to conquer the world. Stopping the campaign caused an even worse disaster...''

'''Author:''' Dugi

'''Status:''' WiP (but Part I might be considered complete)

'''Length:''' 185 (+7 talk-only) scenarios at the moment

'''Difficulty:''' Normal

'''Style:''' mostly Skirmish and Dungeon (all other styles are present as well, but less frequently)

'''Faction/Era:''' Elves, Loyalists, Undead, Dwarves; but they advance past their usual maximum level

'''Version:''' 2.5.0

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Legends_of_the_Invincibles Players Review]'''

'''Note:''' The most unique feature of this campaign is its RPG-like unit development system, enemies drop items units can use, leaders are stronger than most usual units and all units get AMLA (after maximum level advancement) after reaching their maximum level (that is also increased by a load of additional level 4 units).

=== Panther Lord ===

''The Imperialists ambitions of pushing into the Sea States have been repeatedly thwarted and now they turn their attentions elsewhere. You are an outcast Darklander now living as a mercenary in the Sea States and the rumors you hear indicate that they will be coming to your people. Though an outcast you do not wish to see them subjugated. The spirit whose friendship caused you to be an outcast has a plan that might allow you to save them.''

'''Author:''' Velensk

'''Maintainer:''' Lavender

'''Status:''' Finished

'''Length:''' 14 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Era of Four Moons, Darklanders (+ a wide variety of mercenaries)

'''Version:''' 1.0.2

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34318

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Panther_Lord Players Review]'''

=== Random Campaign ===

''Gain experience playing the Default Era faction of your choice in a campaign setting''

'''Author:''' SigurdFireDragon

'''Status:''' Complete

'''Length:''' 7 playable scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Age of Heroes, & Era of Legends

'''Version:''' 1.0.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=32922

'''Note:''' (Author) A 4 scenario version is under the multiplayer button, which lets you choose any era.
Intended for players to gain practice with a faction and learn sound strategies using faction specific adjustments against random factions from the chosen era.

=== Rebellion in the North ===

''A great orcish uprising tends to destabilise the Northlands. As the future Lord Protector of the Northern Alliance you have to crush the rebellion and establish peace again."

'''Author:''' chak_abhi

'''Status:''' Finished

'''Length:''' 24 playable scenarios / 3 dialogue only,2 cutscenes

'''Difficulty:''' Normal

'''Style:''' Skirmish, Large Battle

'''Faction/Era:''' Loyalists, Dwarves, Gryphons, Merfolk

'''Version:''' 1.1.12

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=33059

=== Return of the Monster ===

''It was time for Amailoss, born from the naga queen's last egg, to leave home. Time for him to grow into a leader in his own right, and eventually become the guardian and leader of another naga city. But along the way, he became friends with an unusual mud-crawler, they met a strange young monster, discovered that a spirit had escaped from an orc prison, and the mystery of that spirit became a grave challenge for Amailoss and the many races in the region....''

''A naga campaign, involving elves, orcs, saurians, turtle-like races, and some monsters.''

'''Author:''' SkyOne

'''Status:''' Complete

'''Length:''' 16 playable, 2 dialog scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon

'''Faction/Era:''' Default with additions. You play a custom naga faction and carapaces (a turtle-like race).

'''[http://units.wesnoth.org/1.10/Return_of_the_Monster/en_US/Return_of_the_Monster.html Custom units]'''

'''Version:''' 0.7.1

'''Required Wesnoth version:''' 1.10.x

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36438

=== Return to Noelren ===

'''Status:''' Complete.

'''Length:''' 26 scenarios + 7 cut scenes

'''Author:''' Pyrophorus

'''Description:''' ''A story in the first Dark Age of Wesnoth. See how various heroes stick together to shun the threat of black magics, restore the secret kingdom of Noelren and install Garard I on the throne of Wesnoth. This campaign features complex scenarios, unusual objectives and units, emphasizing more on story and adventures than hardcore fighting.''

'''Version: ''' 0.7.6

'''Requirements:''' BfW 1.10 (not tested on 1.11)

'''Difficulty:''' Easy, unbalanced

'''Style:''' Skirmish, RPG, Large Battle, Simulation

'''Faction/Era:''' Default + custom units

'''[http://units.wesnoth.org/1.10/ReturnToNoelren/en_US/ReturnToNoelren.html Custom Units]'''

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34685#p501026

'''Note:''' (Adamant14) I never saw so much fantastic and new ideas in one single UMC, wow!

=== Return to Ruins ===

''The humble farmers of Vertegris are summoned by Erik the General of Weldyn to put an end to an orcish raiding party. If they knew what would befall their former home... They never would have left. This is a relatively short campaign with 8 scenarios, It is still undergoing changes.''

'''Author:''' Jeff Stevens (Ulfsark)

'''Composer:''' Paul Fredericks (paulfredericksmusic.com)

'''Status:''' Complete

'''Length:''' 7 scenarios + 1 dialogue-only

'''Difficulty:''' Easy,Normal,Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default,(Loyalists, Outlaws)

'''Version:''' 0.5.1

'''Required Wesnoth version:''' 1.10.x

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37790&sid=9059f18497cda1219f42a626544d0ffd&p=540646#p540646

'''Note:''' (Adamant14) You play a short campaign with just a few units. Playable in a few hours, nevertheless it is fun to play.

=== Salt Wars ===

''Introductory campaign for the Era of Four Moons.''

''As an officer of one of the Sea States you must defend your organization from aggressive rivals.''

'''Author:''' Velensk

'''Maintainer:''' Lavender

'''Status:''' Complete

'''Length:''' 5 scenarios

'''Difficulty:''' Easy

'''Style:''' Skirmish

'''Faction/Era:''' Era of Four Moons, Sea States

'''Version:''' 0.2.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=31498

=== Saving Elensefar ===

''Meneldur, elvish mariner of Elensefar, is driven to sea by the same orcs who attacked the city. He must gather an army willing to fight for him to regain Elensefar, his adopted homeland.''

'''Author:''' Turin

'''Maintainer:''' trewe

'''Status:''' Finished

'''Length:''' 1 year (around 12 scenarios)

'''Difficulty:''' Normal

'''Style:''' Skirmish, RPG, Simulation

'''Version:''' 1.5.2

'''Faction:''' Default Era

'''Forum:''' http://wesnoth.org/forum/viewtopic.php?t=3072&start=0

'''Wiki:''' [[SeafaringCampaign]]

'''Note:''' Labeled as Expert, recruit list changes in all scenarios.

=== Shameless Crossover Excuse ===

''Fugitive dark sorcerer Gwiti Ha'atel discovers he has the power to mess with Wesnoth's continuity. His quest for revenge on the NPCs who have used his portraits will lead him through perils untold and in-jokes unnumbered, but shall pale before the horror he finds at his quest's end.''

'''Author:''' Orcish Shyde, Mountain_King

'''Status:''' Complete

'''Length:''' 9 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Version:''' 1.1.0

'''Faction:''' Undead

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=32016&start=15

=== Swamplings ===

''Banished by Yushnak the Ponderer, a tribe of lowly swamp goblins endure in the deadly mire of Pogo Bog. Four centuries before the founding of Wesnoth, this is the story of the goblins' struggle against the intrigues and betrayals of the greater races, and the rise of the first wolf rider.''

'''Author:''' John Rawlins (boru)

'''Status:''' Complete

'''Length:''' 14 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Version:''' 1.1.7n

'''Faction:''' Goblins

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=29784

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Swamplings Players Review]'''

=== Talentless Mage===

''Humorous and silly campaign about mage apprentice who has managed to learn only one simple spell in thirty years.''

'''Author:''' Wonderboy

'''Status:''' Complete

'''Length:''' 11 playable scenarios + 3 dialogue scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Noob Faction

'''Version:''' 1.1.0

'''Forum:''' http://wesnoth.org/forum/viewtopic.php?f=8&t=27608]

'''[http://wiki.wesnoth.org/index.php?title=Guide_to_UMC_Campaigns/Players_Reviews&action=submit#Talentless_Mage Players Review]'''

=== The Dark Alliance===

''Prince Terhar lived two years with elves. Little did he expect what would happen when he returned back to Weldyn.''

'''Author:''' Wonderboy

'''Status:''' Complete

'''Length:''' 11 or 10 playable scenarios depending on the branch you take (+ 5 dialogue scenarios)

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default: Recruit list changes in almost every scenario

'''Version:''' 1.0.3"

'''Forum:''' http://wesnoth.org/forum/viewtopic.php?f=8&t=26924

=== The Dark Hordes ===

'''Status:''' Incomplete/WIP

'''Length:''' 11/?

'''Author:''' Circon

'''Maintainer:''' Various

'''Description:''' Lead fugitive dark sorcerer Gwiti Ha’atel to mastery of the undead hordes.

'''Version: '''

'''Requirements:'''

'''Difficulty:'''

'''Style:''' Skirmish

'''Faction/Era:''' Default undead

'''[http://units.wesnoth.org/1.10/The_Dark_Hordes/en_US/The_Dark_Hordes_1.html Custom Units]'''

'''Walkthrough:''' [[TheDarkHordes]]

'''Forum:''' [[http://forums.wesnoth.org/viewtopic.php?f=8&t=16576&]]

=== The Devil's Flute ===

'''Status:''' Complete, unmaintained

'''Length:''' 10 scenarios

'''Author:''' lipk

'''Description:''' Creona, the well-known assassin, gets a strange job from a strange person. So, in fact, it's no surprise that things take a strange turn...

'''Version:''' 0.1.4c

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish, Minigames

'''Faction/Era:''' Outlaws

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36044

=== The Earth's Gut ===

''The year is 515YW. You are the young dwarven leader Hamel. Your tribe in the caves of Knalga is under pressure from its enemies, and resources are growing scarce. In order to forge the weapons required to resist your enemies, you must set forth and collect what ores and minerals remain.''

'''Author:''' Anonymissimus

'''Maintainer:''' Anonymissimus

'''Status:''' WIP, story is unfinished (I didn't add any scenario since long, but that doesn't mean nothing is added to the campaign. My addons tend to be in good shape and bug-free which means also WIP as I'm updating it since 1.4 days.)

'''Length:''' 23 scenarios, 5 of which are cutscene only, some others have changing objectives

'''Difficulty:''' Normal

'''Style:''' Dungeon, Skirmish

'''Faction/Era:''' Default, dwarves, woses, mages, a few custom units

'''[http://units.wesnoth.org/1.10/The_Earths_Gut/en_US/the_earths_gut.html Custom units]'''

'''Version:''' 0.2.14

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=26800

'''Note:''' This campaign is a "Dwarvish dungeon crawler" (It currently contains about as many surface scenarios as underground though.) and is intended to be challenging for experienced players on hard whilst suitably easy on easy.

=== The Epic of Vaniyera ===

''The expansionist Lavinian Legion, led by the Imperator himself, has invaded the northern forests of the Sidhe, or Wild Elves. It is up to Leithan the Thunderblade and his advisor Vaniyera to push its armies back where they came from...''

'''Author:''' oreb, turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 6 scenarios

'''Difficulty:''' Hard (Don't be fooled by "novice level" in the campaign description, this one is very hard.)

'''Note:''' (Maintainer) Working on this issue, the next release (due at the end of November, hah!) should bring easy difficulty back to the level of a reasonable introduction to the IE, while the hard difficulty will also become slightly easier. With any luck, this will be the last release before version 1.0 of the campaign].

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Sidhe.

'''Version:''' 0.9.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=19490

=== The Fall of Wesnoth ===

''As the beloved human empire of Wesnoth becomes lazy and arrogant in its peaceful state of happiness, Emperor Dantair demands the creation of another sun in a bid to destroy all evil. Or is it all for a different purpose? A man named Alitar sees it that way, and now he must survive the most evil inhabited lands if he is to stop chaos from rising, and Wesnoth from falling... This is the story of The Fall of Wesnoth.''

'''Author:''' Pewskeepski

'''Status:''' 1st part complete, 2nd WIP.

'''Length:''' 10 playable scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Outlaws

'''[http://units.wesnoth.org/1.10/The_Fall_of_Wesnoth/en_US/The_Fall_of_Wesnoth-1.html Custom units]'''

'''Version:''' 1.0.8

=== The Founding of Borstep ===

''The chieftain of your tribe has become decadent and weak. Take over, and lead your people to a better home--whether it is already occupied or not. The Northlands in year 9W are a barbaric place, but anyone who stands in your way will learn the power of orcs!''

'''Author:''' Beetlenaut

'''Status:''' Complete

'''Length:''' 10 and 1 dialogue only

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default, Northerners

'''[http://units.wesnoth.org/1.10/The_Founding_of_Borstep/en_US/The_Founding_of_Borstep.html Custom units]'''

'''Version:''' 1.1.1b

'''Note:''' (Kanzil) I find the protagonist hard to sympathise with. Also, most scenarios contain interesting twists. For example, in one, each time you killed a boar it gives you extra health.

'''Note:''' (beetlenaut--author) In most Orcish campaigns the leader is heroic or just wants peace. Krag-Ubor wants plunder and battle like all enemy Orcs in other campaigns. I '''hope''' you don't sympathize too strongly, but I don't think you need to in order to enjoy the game play.

=== The Library of Kratemaqht ===

''An ancient story from the old continent.''

'''Author:''' Rich Marinaccio (cephalo)

'''Status:''' Complete

'''Length:''' 17 scenarios

'''Difficulty:''' Unbalanced (some scenarios are Easy - some rather Hard)

'''Style:''' Skirmish, RPG

'''Faction/Era:''' Loyalists and custom units.

'''[http://units.wesnoth.org/1.10/Library_Of_Kratemaqht/en_US/The_Library_Of_Kratemaqht.html Custom units]'''

'''Version:''' 1.0.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37798

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#The_Library_of_Kratemaqht Players Review]'''

'''Notes:''' (Adamant14) This campaign has a thought-out story, shows a great love for detail;
It includes a great custom Dragon, some brilliant custom images (fire, burning houses, burning forest) that makes the scenery / maps look very nice.

=== The Roar of the Woses ===

''When the construction of a dam threatens the existence of her home, Kylix is forced on a journey to stop it.''

'''Author:''' Alarantalara

'''Status:''' Finished

'''Length:''' 10-11 scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default with Additions (primarily Saurians, Nagas, Woses)

'''Version:''' 1.2.7

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=29830

'''Note:''' (author) Potentially unbalanced on Hard difficulty due to experiments with non-standard ways to increase difficulty. This issue does not exist on the lower difficulty levels.

=== The Three Elves ===

''Three elves have just begun their adventure in the northern swampland. Will they become heroes or will they be responsible for another undead expansion?''

'''Author:''' Stanislav Hoferek

'''Maintainer:''' trewe

'''Version:''' 0.9

'''Status:''' Complete

'''Difficulty:''' Easy

'''Length:''' 8 scenarios + 2 dialogue

'''Style:''' Skirmish

'''Faction:''' Default (Elves)

'''Forum:''' (does it have one?)

=== The Sojournings of Grog ===

''Grog (as starred in Under the Burning Suns) goes home.''

'''Author:''' Peter Christopher, Thomas Hockings

'''Maintainer:''' Elvish_Hunter

'''Status:''' Finished

'''Length:''' 18 playable scenarios in 2 parts

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon, Large Battle

'''[http://units.wesnoth.org/1.10/The_Sojournings_of_Grog/en_US/The_Sojournings_of_Grog.html Custom units]'''

'''Faction/Era:''' Default. Most of the time you play trolls and some desert elves accompanying Grog.

'''Version:''' 3.0.1

=== The Unstoppable Legion ===

''Horseback campaign. The kingdom of Suveran, far away from Wesnoth, is under attack. Only Deuterus, a Great Druid, knows their weakness and only Viktor, a young noble, dares go on the quest to stop them.''

'''Author:''' Chris Neville-Smith (Chris NS)

'''Maintainer:''' Chris Neville-Smith (Chris NS)

'''Status:''' WIP

'''Length:''' Currently 15 playable sceanrios, including a fork of three paths near the beginning, and another fork of two paths later on.

'''Difficulty:''' Normal

'''Style:''' Mainly Skirmish

'''[http://units.wesnoth.org/1.10/The_Unstoppable_Legion/en_US/The_Unstoppable_Legion.html Custom units]'''

'''Faction/Era:''' Play mounted units, including expanded Cavalryman line, and completely new Bowrider line. Joined later by Dwarves. Main enemies are the dark fighters and dark cultists.

'''Version:''' 0.8.7

=== The White Troll ===

''The story of a white troll whelp with strange magic powers, who is raised in an elvish village.''

'''Author:''' Wesnoth Italian Forum

'''Status:''' Complete

'''Length:''' 8 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default: you play with elves and trolls. Also features custom units with special advancements and abilities.

'''[http://units.wesnoth.org/1.10/White_Troll/en_US/white_troll.html Custom Units]'''

'''Version:''' 0.7.5

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=38828

=== To Lands Unknown ===

''This is the story of Mehir, the Summoner, and his journey to lands unknown.''

'''Author:''' inferno8

'''Status:''' Complete

'''Length:''' 20 scenarios, 4 dialogue only

'''Difficulty:''' Intermediate (Era of Magic)

'''Style''': Skirmish, Dungeon

'''Era:''' Era of Magic

'''Version:''' 1.6.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=31799

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#To_Lands_Unknown Players Review]'''

=== Unlikely Alliance ===

''Play as the members of an alliance between the elves, drakes, and undead after the Fall of Wesnoth.''

'''Author:''' Creativity

'''Status:''' Broken ( Abandoned )

'''Length:''' 2 broken scenarios

'''Difficulty:''' Unbalanced

'''Style:''' -

'''Faction/Era:''' -

'''Version:''' 0.1

'''Forum:''' -

'''Note:''' (Adamant14) Did not work at all. Seems abandoned.

=== Up from Slavery ===

''The Orcei are captives in the imperial city of Lavinium, gladiators performing for the emperor Optus Maximus. All it will take, however, is one orc to lead his people to freedom. The Samnis called Sparxus may be that orc.''

'''Author:''' turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 7 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish, Arena (= No recruit, small group gladiator fights)

'''Faction/Era:''' Imperial Era, Orcei Gladiatores

'''Version:''' 0.6.0

'''Note:''' (Maintainer) At some point, I am intending to completely re-work this campaign to be a multi-player campaign, with one side led by Sparxus and one by Gravirivus. If anyone would like to take this on or has ideas for how to accomplish this, let us know. Nevertheless, its playable as a single player campaign now with some nice ideas that could be developed further.]

=== Warmaster ===

''One day the scout of your king brings a mysterious little stone, called Zrai-Stone, back from one of his trips. Soon that stone causes a lot of trouble...''

'''Author:''' Conkinator

'''Maintainer:''' trewe

'''Version:''' 1.3.5

'''Status:''' Finished

'''Length:''' 16 battle + 2 bonus + 1 epilogue scenarios

'''Difficulty:''' Hard

'''Faction:''' Default (loyalists)

'''Style:''' Skirmish, Survival

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=15527

=== Way of Dragon ===

''The story of what might happen if a person against his will transform into a dragon...''

'''Author:''' DrakeDragon

'''Status:''' Complete

'''Length:''' 7 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish/RPG

'''Faction/Era:''' Default Loyalists

'''Version:''' 1.2.0

'''Forum:''' [http://forums.wesnoth.org/viewtopic.php?f=8&t=37876 Wesnoth Forum] [http://uporoom.ru/index.php/topic,179.0.html Russian Forum]

'''Note:''' (Adamant14) Promising short campaign, you play with just a few units.

== Battle for Wesnoth 1.11.x - development ==

''Campaigns available in the 1.11.x development version.''

''Please note: Battle for Wesnoth 1.11.0 features a bug that messes up the selection of difficulty levels.''

=== Antar, Son of Rheor ===

''This is the story about a young Lord and his first mission; sent by his father the young Lord Antar has to relieve his neighbours; he has to convince the Elves and Dwarves to ally him; he has to fight against hordes of Orcs and Endless Undead; and finally he has to defeat Mal Kazur, the mastermind who is behind all the evil.''

'''Author:''' Adamant14

'''Status:''' WIP

'''Length:''' 9 playable scenarios / 1 cutscene

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Loyalists and Elves (feat. fencer as main hero + various allies)

'''Version:''' 0.9.9

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36075

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Antar.2C_Son_of_Rheor Players Review]'''

'''Note:''' (Adamant14) The campaign did not work with BfW version 1.11.0, or BfW version 1.11.1, so please use BfW version 1.11.2 or later!

=== A Song of Fire ===

''''''Part I: The Last War''' - In a long-forgotten era, at the heart of the Great Continent, an ancestral evil is awakened, threatening to destroy the whole world. Follow young Myra in the war that will alter the future of Irdya and its peoples forever.''

''''''Part II: Towards the Rising Sun''' - After the vicious Last War, Myra has become the new leader of Aragwaithi and Windsong alike. Albeit young and shaken by many losses, she must steel herself to lead her people through the vast and hostile Hannuk Steppes. However, her journey will take them all farther than in their wildest dreams. Furthermore, Myra must deal with the evil influence of the mysterious red gem she found after the last battle.''

''''''Part III: Raging Skies''' - The refugees have finally found a new home: families are built, allies are made and, for the first time in years, Myra and her friends know peace. However, when everything seems normal, ambition and thirst for power cause the break out of a continental war. And, amidst this new storm, an old foe rises agan, more powerful than ever. Witness the end of the song of Irdya's first great heroine.''

'''Author:''' revansurik

'''Status:''' Complete

'''Length:''' 36 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish, Large Battle

'''Faction/Era:''' Default+War of Legends

'''Version:''' 0.3.4

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=38210

=== Bad Moon Rising ===

''An expedition to gather treasure from the cold north sets off compounding disaster.''

'''Author:''' Doofus-01

'''Status:''' Finished

'''Length:''' 20 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Archaic Era

'''Version:''' 1.5.8

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=31348

=== Birth of a Lich ===

''This is the life story of the dreaded lich Malifor, his struggle as a mage outcast, the orcish conquest of the northlands and his transformation to quench the thirst for revenge''

'''Author:''' chak_abhi

'''Status:''' Finished

'''Length:''' 12 playable scenarios / 2 dialogue only

'''Difficulty:''' Normal

'''Style:''' Skirmish, Large Battle, Dungeon

'''Faction/Era:''' Human outlaws, dwarves, undead

'''[http://units.wesnoth.org/1.10/Birth_of_a_Lich/en_US/Birth_of_a_Lich.html Custom Units]

'''Version:''' 1.0.3

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37057

=== Coming of the Storm ===

''A new recruit joins the imperial army, eager to change the world and see combat. Little does he realise just how much action he will get and where his journey will take him. ''

'''Author:''' TrashMan

'''Status:''' WIP

'''Length:''' 26 playable scenarios / 4 dialogue only

'''Difficulty:''' Normal

'''Style:''' Skirmish, Large Battle, Dungeon

'''Faction/Era:''' Default

'''Version:''' 1.2.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23361

=== Legend of Far North ===

''The tale of the legendary Black Eye Karun,depicting his rise to power, his successes and his brutal assassination.'

'''Author:''' chak_abhi

'''Status:''' Finished

'''Length:''' 16 playable scenarios / 1 dialogue only,1 cutscene

'''Difficulty:''' Normal

'''Style:''' Skirmish, Large Battle

'''Faction/Era:''' Orcs, Trolls, Saurians, Nagas

'''[http://units.wesnoth.org/1.10/Legend_of_Far_North/en_US/Legend_of_Far_North.html Custom Units]'''

'''Version:''' 1.0.2

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34769

=== Legend of the Invincibles ===

'''''Part I: Shrouded in Darkness''' (5 chapters, 90 scenarios) - A pair of heroes, after stopping an orcish thread, are outcast into caves, where they have no other choice than to become liches in order to survive. They preserved their original appearance and moral principles, and fight in various skirmishes against evil (although using evil methods sometimes), until the Fall, when they are buried alive under the ashes of the third sun.''

'''''Part II: Into the Light''' (4 chapters, 96 scenarios at the moment) - Long after the Fall, the lich heroes awaken. Searching for more power, they manage to resurrect themselves as living beings, but this time more powerful and ridden of the evil within. But the evil from inside them did not cease to exist, and started a campaign to conquer the world. Stopping the campaign caused an even worse disaster...''

'''Author:''' Dugi

'''Status:''' WiP (but Part I might be considered complete)

'''Length:''' 185 (+7 talk-only) scenarios at the moment

'''Difficulty:''' Normal

'''Style:''' mostly Skirmish and Dungeon (all other styles are present as well, but less frequently)

'''Faction/Era:''' Elves, Loyalists, Undead, Dwarves; but they advance past their usual maximum level

'''Version:''' 2.5.0

'''[http://wiki.wesnoth.org/Guide_to_UMC_Campaigns/Players_Reviews#Legends_of_the_Invincibles Players Review]'''

'''Note:''' The most unique feature of this campaign is its RPG-like unit development system, enemies drop items units can use, leaders are stronger than most usual units and all units get AMLA (after maximum level advancement) after reaching their maximum level (that is also increased by a load of additional level 4 units).

=== Rebellion in the North ===

''A great orcish uprising tends to destabilise the Northlands. As the future Lord Protector of the Northern Alliance you have to crush the rebellion and establish peace again."

'''Author:''' chak_abhi

'''Status:''' Finished

'''Length:''' 24 playable scenarios / 3 dialogue only,2 cutscenes

'''Difficulty:''' Normal

'''Style:''' Skirmish, Large Battle

'''Faction/Era:''' Loyalists, Dwarves, Gryphons, Merfolk

'''Version:''' 1.1.12

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=33059

=== Ruthless ===

''A bard (an aging criminal) is walking in wasteland. Nothing but two hands in his pockets, and nothing but stones around. Suddenly he sees a knight on errand--a dangerous opponent, especially in broad daylight. The two strangers are soon sitting by the campfire, and the bard is telling a story.
(Beginner level, 10+ fights).''

'''Author:''' homunculus

'''Status:''' Finished

'''Length:''' 12 playable scenarios + 5 cutscene scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default (Orcs)

'''Version:''' 1.0.4

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37874

'''Note:''' (Adamant14) Recommendable campaign, with smart unusual ideas and a good detailed story.
You fight with few units on small but perfect maps. About the difficulty: The author describes his campaign as 'beginner level', but for me the difficulty is rather NORMAL than EASY.

== [[Guide_to_UMC_Campaigns/Players_Reviews|Player Reviews]] ==

[[Category:Campaigns|*]]

StandardSideFilter

2013-04-30T14:49:02Z

Anonymissimus: document controller= in SSFs

{{WML Tags}}

From [[FilterWML]], this is the standard way of filtering on sides. Often a SSF needs to be included in a [filter_side] tag. There are however also many tags that take the SSF tags and keys directly as arguments.

The following attributes and sub-tags are permitted:

* '''side''': filter matches only if side number is contained in a comma-separated list. Note that as opposed to the usual inline side= key in wml action tags, which defaults to 1, the side= key in a SSF defaults to all sides (similarly, the id= key in SUFs defaults to all ids)
**{{DevFeature1.11}}: This key accepts ranges (i.e. "1,3-4,6")
* '''[has_unit]''':
**'''[[StandardUnitFilter]]''': filter matches only if side controls a unit matched by it
**'''search_recall_list''': (boolean yes|no, default no) whether to include recall list units when trying to match this [[StandardUnitFilter]] against a unit

* '''team_name''': The currently filtered side matches only if this passed team_name is contained in its (the filtered side's) team_name= string. Note that a side can be allied/on the same team like 2 (more...) other sides which can be enemies at the same time. (achieved by defining a side via [side]team_name=1,2 etc.)

* '''[enemy_of]''': The currently filtered side must be an enemy of all of the sides matching this StandardSideFilter for it to match. If this inner StandardSideFilter matches no sides, the outer filter also doesn't. Note that a side is not an enemy of itself.
**StandardSideFilter tags and keys

* '''[allied_with]''': The currently filtered side must be allied with all of the sides matching this StandardSideFilter for it to match. If this inner StandardSideFilter matches no sides, the outer filter also doesn't. Note that a side is allied with itself.
**StandardSideFilter tags and keys

* '''controller''': The currently filtered side matches only if it has this controller string. Sensible values are ai, human, human_ai (:droided human side) and null. This key is disabled for networked multiplayer, since there the controller value of a side differs between the clients. Thus using this key would inevitably lead to OOS errors.

Also, [and], [or], and [not] subfilters are supported.

Interaction of SSF and side= in tags like [remove_shroud] :
In case that inline side= and [filter_side] are given, inline side= is ignored and [filter_side]side= gets priority:

selects side 4 and 5:
[remove_shroud]
side=2
[filter_side]
side=4,5
[/filter_side]
[remove_shroud]

EventWML

2013-02-04T19:03:46Z

Anonymissimus: /* The 'name' Key (Mandatory) */ Add a comment about [event]name= vs [event]id=

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

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

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

'''Lexicon side note:''' ''The word "event" in the [event] tag itself may be considered an abbreviation of the word "event handler" because it is technically not a game "event" but an event '''handler''' for the game events fired with the given 'name'. However, this distinction is usually unimportant in most discussions and the event handlers are therefore simply referred to as "events" in this documentation.''

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

Usage:
name=<value>

This key defines which game event or trigger your [event] tag will be handling. This 'name' key should not be confused with a descriptive comment; it is rather a precise value which must match the predefined game event's name to be valid.

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

''* A better name for the [event]name= attribute could be [event]class= or [event]type=, these describe much better their functionality. The attribute determines to which group of events the event belongs and all of them are fired by the same action. This is opposed to [event][[EventWML#Optional Keys and Tags|id]]=, which refers only to the event in which it appears.''

==== 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
: 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 at the start of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. Before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.

; turn end
: Triggers at the end of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. The WML variable '''side_number''' will contain the side that ended their turn.

; turn ''X'' end
: Triggers at the end of turn ''X''.

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

; ai turn
: Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side. Note that this event might be called several times per turn in case that fallbacks to human or droiding is involved. I.e. it happens at the middle of turn of human side 1 if the human player droids his side. It happens after the selection of ai to play the turn but before AI is told that new turn has come.
: '''Note:''' ''This event currently breaks replays since it is not explicitly saved in a replay and there is no AI involved in replays...''

; turn refresh
: Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status.
: Note that the turn refresh event does occur on turn 1, even though healing, income and unit refreshing do not.

; turn ''X''
: Triggers at the start of turn ''X''. It's the first side initialization event.
:Side initialization events go in the order of:
: 1) '''turn ''X'''''
:2) '''new turn'''
:3) '''side turn'''
:4) '''side ''X'' turn'''
:5) '''side turn ''X'''''
:6) '''side ''X'' turn ''Y'''''
:7) '''turn refresh'''
:8) '''side ''X'' turn refresh'''
:9) '''turn ''X'' refresh'''
:10) '''side ''X'' turn ''Y'' refresh'''

; side ''X'' turn ''Y''
: This event triggers at the start of turn ''Y'' of side X

; side ''X'' turn
: This event triggers at the start of any turn of side X
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; side turn ''X''
: This event triggers at the start of any side on turn X
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; side X turn Y refresh
: This event triggers at the turn refresh for side X on turn Y

; side ''X'' turn refresh
: This event triggers at the turn refresh for side X
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; turn ''X'' refresh
: This event triggers for any side at the refresh of turn X.
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; side turn end
: Triggers after a side ends its turn. Like side turn, there are also some variations for specific combinations of side number and turn number. Here is the order in which the turn end events trigger:
:1) '''side turn end'''
:2) '''side ''X'' turn end'''
:3) '''side turn ''X'' end'''
:4) '''side ''X'' turn ''Y'' end'''
:5) '''turn end'''
:6) '''turn ''X'' end'''

; 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 (except [filter_condition] which is for all sorts of events) can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true.
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]. weapon and second_weapon variables are available inside attack, attacker_hits, defender_hits, die and last_breath events. See [[VariablesWML#Automatically_Stored_Variables|automatically stored variables]] for more information.

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

; sighted
: '''important: "sighted" events are very buggy in general, especially if "delay shroud updates" is set to "yes". It is recommended to avoid using them at all costs, especially if you want to change the gamestate in that event (such as setting variables). Trying to document all the exceptions under which a sighted event doesn't fire or does not work as expected is futile - please keep that in mind.'''
: '''Alternatives:''' It is sometimes possible to replace a sighted event by a moveto event with a [[StandardLocationFilter|location filter]] matching a nearby location. A [[FilterWML#Filtering_Vision|filter_vision]] filter may be useful in some cases. There exists a macro in mainline which provides a workaround: ON_SIGHTING, see http://www.wesnoth.org/macro-reference.xhtml
: A '''sighted''' event is triggered when a fog or shroud is lifted from the primary ''unit''. This can happen when a ''second_unit'' moves to a nearby location and discovers the primary ''unit''. It does not, however, fire if the primary unit emerges "out of the mist". (This is part of the sighted event's bugs.)
: '''Note:''' The sighted event is ''only'' triggered when a unit moves from one location to another. When the player moves to attack an enemy unit and, in the process, removes the fog/shroud over an enemy unit, the sighted event does ''not'' fire. This makes the sighted event unreliable: It may or may not fire, depending on the user actions. (This may be part of the sighted event's bugs.)

: {{DevFeature1.11}} Sighted events have been fixed. A '''sighted''' event is triggered by a unit becoming visible to a side (other than the unit's own side). This is mostly useful when the side seeing the unit uses [[fog of war]] or [[shroud]], but they still fire even when fog/shroud is not in use, and they do take into account the {{tag2|AbilitiesWML#The_.5Babilities.5D_tag|hides}} ability. The ''primary unit'' is the unit that became visible, and the ''secondary unit'' belongs to the side that now sees the primary unit. In some cases, sighted events can be delayed from when they "should" occur. If that happens, the secondary unit will be filtered as if it was at the location where the event "should" have occurred, and ''x2,y2'' will store that location (not the current position of the secondary unit). To understand when sighted events fire, it is helpful to distinguish the times the acting unit sights other units from the times when the acting unit is sighted.
: An acting unit can sight other units when it is recruited, recalled, leveled, or moved, and when fog or shroud is cleared from occupied hexes as a result. In these cases, the acting unit is always the ''secondary unit''. For the first three actions, there are two events associated with the action; clearing occurs between these events, but any sighted events are fired after the second event. (For example, when a unit is recruited, the ''prerecruit'' event fires, then fog is cleared, then the ''recruit'' event fires, then ''sighted'' events fire.) For movement, the sighted events fire between ''enter_hex'' and ''exit_hex'' events, but sometimes sighted events are postponed until the moving unit reaches a good place to stop (e.g. not in an occupied hex). As a major exception to the above, players have the option to delay shroud (and fog) updates. If the player delays shroud updates, sighted events are also delayed until the shroud is updated.
: An acting unit can be sighted by other sides when it is recruited, recalled, leveled (in rare cases), or moved. In these cases, the acting unit is always the ''primary unit''. These events fire after sightings by the acting unit (unless the player delayed shroud updates). For the first two, the sighted event fires for all sides that can see the unit, other than the unit's own side (even if those sides use neither fog nor shroud). For leveling units, sides that could see the unit before it leveled are excluded. (This is why these events are rare – the leveling unit must have lost a [hides] ability as a result of leveling in order to be seen after, but not before, leveling.) For movement, a sighted event is fired for each side that could see the unit after movement, but not before. In particular, only the starting and ending hexes are considered; a unit that moves through seen hexes but ends movement in a fogged hex does not trigger a sighted event for itself. In all cases where the acting unit is sighted, a (single) ''secondary unit'' is chosen from the sighting team. This choice should be considered arbitrary, but units within their sight range of the acting unit are chosen in preference to units further away.
: Sighted events have some special caveats for WML authors. First and foremost, {{tag|DirectActionsWML|allow_undo}} should generally be avoided in sighted events. It can be used if current unit positions have no bearing on the event, but otherwise it could cause a replay to go out of sync if a player delays shroud updates and undoes a move. This should not be an onerous restriction, though, as clearing fog will block the ability to undo, regardless of what happens within an event. Secondly, it is currently possible for WML to kill a unit involved in a sighted event before that event fires. If that happens, filters on the killed unit will not match anything and the event may seem to have not fired.

; enter_hex
: {{DevFeature1.11}} Triggers for each hex entered during movement, with $x1,$y1 identifying the hex entered and $x2,$y2 identifying the previous hex (just exited). If this event is handled without using {{tag|DirectActionsWML|allow_undo}}, then movement is interrupted, stopping the unit where it is.
: '''Note:''' This event behaves a bit unusually if the hex is occupied (and the moving unit is simply passing through). When this happens, $x1,$y1 is still the hex where the event was triggered, but the moving unit (stored in $unit) will be located somewhere earlier in the route (the most recent unoccupied hex). That is, $x1,$y1 will not equal $unit.x,$unit.y (a condition that can be used to detect when the entered hex is occupied). The moving unit will have already spent its movement points to enter the event's hex even though it is has not actually moved from the most recent unoccupied hex.

; exit_hex
: {{DevFeature1.11}} Triggers for each hex exited during movement, with $x1,$y1 identifying the hex exited and $x2,$y2 identifying the next hex (to be entered). If this event is handled without using {{tag|DirectActionsWML|allow_undo}}, then movement is interrupted, stopping the unit where it is.
: '''Note:''' This event behaves a bit unusually if the hex is occupied (and the moving unit is simply passing through). When this happens, $x1,$y1 is still the hex where the event was triggered, but the moving unit (stored in $unit) will be located somewhere earlier in the route (the most recent unoccupied hex). That is, $x1,$y1 will not equal $unit.x,$unit.y (a condition that can be used to detect when the exited hex is occupied). The moving unit will have already spent its movement points to enter the event's hex even though it is has not actually moved from the most recent unoccupied hex.

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

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

; last breath
: Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered. Use this instead of name=die when you want the primary unit to make a final [message].

; die
: Triggers when the primary unit is killed by the secondary unit. ''Note: The primary unit is not removed from the game until the end of this event. The primary unit can still be manipulated, will block other units from taking its hex, and will still be found by standard unit filters (except [have_unit]). To prevent this behavior, you can use [kill] to remove the unit immediately. However, this will stop any (still unfired) other events that also match the unit from firing afterwards, so use with caution.'' If you want to the primary unit to make a final [message], use name=last_breath, see above.

; capture
: Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture. This event will be fired before the moveto event. Villages becoming neutral (via [capture_village]) do not fire capture events. The variable $owner_side contains the previous owner side of the village. 0 means neutral.

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

; prerecruit
: Triggers when the primary unit is recruited (by the secondary unit) but before it is displayed.

; recall
: Triggers after the primary unit is recalled (by the secondary unit).

; prerecall
: Triggers when the primary unit is recalled (by the secondary unit) but before it is displayed.

; advance
: Triggers just before the primary unit is going to advance to another unit, or advance by AMLA. (This is after the player selects which advancement, if there is a choice). If this event removes the unit, changes the unit's type, or reduces the unit's experience below what it needs to advance, then the advancement is aborted. Due to a bug, the preceding does not apply to advancement by AMLA. {{DevFeature1.11}} The bug has been fixed. (The fix is not in earlier versions because it could introduce an incompatibility.)

; post advance
: Triggers just after the primary unit has advanced to another unit, or advance by AMLA.

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

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

==== 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. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; for example:
: ''first_time_only=yes''
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.
: ''first_time_only=no''
:: The event will trigger every time the criteria are met instead of only the first time.

==== id ====
: If an id is specified, then the event will not be added if another event with the same id already exists. An id will also allow the event to be removed, see below.

==== remove ====
: Whether to remove an event instead of adding a new one. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; if true, then the contents of the event are ignored and the event with the specified id is removed instead. for example:
[event]
id=id_of_event_to_remove
remove=yes
[/event]

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

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

==== [filter_attack] ====
: Can be used to set additional filtering criteria based on the weapon used by the primary unit. This is usable in the events ''attack'', ''attacker hits'', ''attacker misses'', ''defender hits'', ''defender misses'' and ''attack end''. For more information and filter keys, see [[FilterWML#Filtering Weapons|Filtering Weapons]]. The most commonly used keys are the following.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [filter_second_attack] ====
: Like [filter_attack], but for the weapon used by the secondary unit.

==== [filter_condition] ====
: This tag makes sense inside any sort of event - even those that don't have units, or custom events,... The event will only trigger if this condition evaluates to true.
:* [[ConditionalActionsWML#Condition_Tags|Condition Tags]]
: note: This tag is meant to be used when the firing of an event shall be based on variables/conditions which cannot be retrieved from the filtered units.

==== [filter_side] ====
: The current side (usually the side $side_number) must match the passed [[StandardSideFilter]] for the event to fire.
:* SSF tags and keys as arguments as described in [[StandardSideFilter]].
: note: This tag makes most sense in side turn and turn refresh events. However, all wml events have a current side so one could also prevent e.g. a moveto event from firing if you put a [filter_side] tag there and the moving unit's side doesn't match.

==== 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 [[ActionWML|action tags]] within the [event] tag are executed in the order they are written in.

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

More details in [[ActionWML]].

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

=== Nested Events ===

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

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

==== Delayed Variable Substitution ====

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

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

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

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

== Multiplayer safety ==

In multiplayer it is only safe to use WML that might require synchronization with other players because of input or random numbers (like [message] with input or options or [unstore_unit] where a unit might advance) in the following events. This is because in these cases WML needs data from other players to work right and/or do the same thing for all players. This data is only available after a network synchronization.

List of synchronized events:
* moveto
* sighted
* attack
* attack_end
* attacker hits
* attacker misses
* defender hits
* defender misses
* stone
* last breath
* menu item X
* die
* capture
* recruit
* prerecruit
* recall
* prerecall
* advance
* post_advance
* new turn
* side turn
* turn X
* side X turn
* side X turn Y
* turn refresh

There is also the possibility of events that are normally synchronized when fired by the engine but can be non-synchronized when fired by WML tags from non-synchronized event. So when you are using them you must be extra careful. For example [unstore_unit] may trigger a unit advancement that will fire ''advance'' and ''post advance'' events.

== A Trap for the Unwary ==

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

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

=== Event IDs ===

This problem can be avoided by setting an '''id''' on the event, i.e.:

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

Events with the same ID will only be accepted once by the engine no matter how many times they are included, and will only be saved once to the scenario's savefile. Events with an ID can also be removed by using the '''remove''' key, i.e.:

[event]
id=doubler_event
remove=yes
[/event]

After that WML is encountered (at toplevel or after created from another event), the event with this ID is removed from the scenario wml, thus firing it has no effect. After an event is removed, it can still be re-added later.

== 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 a message showing the turn number 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]

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

[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, the following example is identical to the first two in that it will display a message showing the turn number on which the nested ''moveto'' event happens, despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

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

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

=== Multiple Nested Events ===

Every delayed_variable_substitution=no causes a variable substitution run on the subevent where it occurs at the spawn time of this event and on all following subevents. For any specific event, variable substitution happens at least one time when the event is executed. For each delayed=no key appearing in itself or in an event of an "older" generation, which is not the toplevel event, an additional variable substitution run is made.
[event]# parent
name=turn 2
#delayed_variable_substitution=no # In the parent event, delayed= has no effect.

[event]# child
name=turn 3
delayed_variable_substitution=no # Causes variable substitution in the child, grandchild and great-grandchild event
# at execution time of the parent event = spawn time of the child event.

[event]# grandchild
name=turn 4
delayed_variable_substitution=yes # no variable substitution in the grandchild and great-grandchild event
# at execution time of the child event = spawn time of the grandchild event

[event]# great-grandchild
name=turn 5
{DEBUG_MSG $turn_number}# output: 2 - value from the variable substitution at execution time of the parent event,
# caused by delayed=no in the child event

{DEBUG_MSG $||turn_number}# output: "$turn_number"
# Each variable substitution transforms a "$|" to a "$" (except when no | left).

{DEBUG_MSG $|turn_number}# output: 5 - from the variable substitution at execution time
# of the great-grandchild event
[/event]
[/event]
[/event]
[/event]

== See Also ==

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

[[Category: WML Reference]]

EffectWML

2012-11-12T22:36:52Z

Anonymissimus: removal of [effect]unit_type/gender=

{{WML Tags}}

The tag [effect] is used to describe one modification to a unit. Any number of [effect] tags can be used to describe a complete modification. Modifications are permanent changes to a unit; currently there is no way of removing a modification.

The following keys and subtags are always recognized:
* '''[filter]''': only apply this effect if the affected unit matches. See [[StandardUnitFilter]] for details.
* '''unit_type''': only apply this effect if the affected unit's type name matches the value. (can be a list) {{DevFeature1.11}} Support for the key is removed in favor of [effect][filter]type=.
* '''unit_gender''': only apply this effect if the affected unit's gender name matches the value. (can be a list) {{DevFeature1.11}} Support for the key is removed in favor of [effect][filter]gender=.
* '''times''': describes how many times the effect is applied. The default is to apply the effect once. Other possible value : "per level" which means that the effect is applied level times, where level is the unit level.
* '''apply_to''': describes what the effect actually affects.
[effect] uses different keys depending on the value of '''apply_to'''. '''apply_to''' can take the following values:
* '''new_attack''': will use all other keys and tags as the description of an attack that will be added to the unit. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]].
* '''remove_attacks''': remove the matching attacks. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. Do not use a [filter] tag otherwise it will not work properly.
* '''attack''': find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
** '''set_name''': change the attack's name (ie identifier).
** '''set_description''': change the attack's description (ie displayed name).
** '''set_type''': change the attack type. The standard values are '''blade''', '''pierce''', '''impact''', '''fire''', '''cold''', and '''arcane'''.
** '''[set_specials]''': change the attack's specials. The specials to add are given exactly as in the [specials] tag.
*** '''mode''': if '''append''', adds the given specials to the attack. If '''replace''', replaces the existing specials with the given ones. Default '''replace'''.
** '''remove_specials''': remove the listed specials. The value of this key is the coma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
** '''increase_damage''': increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent(''''%''''), the change in damage will be a percentage ratio of the attack's original damage.
** '''increase_attacks''': increases the number of attack strikes. Like '''increase_damage''', it can be positive or negative, or a percentage.
** '''attack_weight''': change the attack's attack_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about attack_weight.
** '''defense_weight''': change the attack's defense_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about defense_weight.
* '''hitpoints''': modifies the unit's HP and/or max HP.
** '''increase''': the amount to increase the unit's HP.
** '''heal_full''': if present and not set to "no" the unit will be put back to full HP.
** '''increase_total''': will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
** '''violate_maximum''': it the unit ends up with more than its max HP after these modifications, and this key is present (set to any non-null value, ex. '''yes'''), the unit's HP won't be lowered to its max HP.
* '''movement''': modifies the unit's movement points.
** '''increase''': maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum movement is set to a specific value.
* {{DevFeature1.11}} '''experience''': affects the unit's current XP.
** '''increase''': current XP is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': current XP is set to a specific value.
* '''max_experience''': affects the amount of XP the unit needs for the next level.
** '''increase''': how to change the xp; again it can be negative, positive or a percentage.
* '''loyal''': no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
* '''movement_costs''': speed through specific terrain is modified
** '''replace''': If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[movement_costs]''': a subtag that describes the new movement costs just like in [[UnitsWML#.5Bmovetype.5D|UnitsWML]]
* '''defense''': Sets unit chance to be hit in specific terrain (100 - defense value)
** '''replace''': If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[defense]''': a subtag that describes the new defense just like in [[UnitsWML#.5Bmovetype.5D|UnitsWML]]
* '''resistance''': Sets percent damage taken from combat
** '''replace''': If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[resistance]''': a subtag that describes the new resistance just like in [[UnitsWML#.5Bmovetype.5D|UnitsWML]]
* '''variation''': switches the unit into one of its variations.
** '''name''': the id of the variation to invoke.
* '''type''': transforms the unit into a new unit_type.
** '''name''': the id of the unit_type to invoke.
* '''status''': modifies the status affecting the unit.
** '''add''': a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [[InternalActionsWML|[store_unit]]] and [[DirectActionsWML|[unstore_unit]]], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], [[SingleUnitWML]].
** '''remove''': a list of status modifications to remove.
* '''zoc''': toggle the zone of control.
** '''value''': new value for zoc (0=disable, other=enable).
* '''profile''': customize the profile of the unit. See [[UnitTypeWML]].
** '''portrait''': new image to display when the unit speaks.
** '''small_portrait''': new image to display in unit reports.
** '''description''': sets the text to display when hovering over the unit's type in the righthand pane.
* '''new_ability''': Adds one or more abilities to a unit.
** '''[abilities]''': A subtag that contains the ability definitions.
* '''remove_ability''': Removes one or more abilities from a unit. Abilities are not reference counted: added, added, removed = gone.
** '''[abilities]''': A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag.
* '''new_animation''': contain animations that will be added to the unit, it can contain multiple animation blocks, and a single "id=" line. That Id should be unique for each effect block and is used by the engine to reuse WML parsing, making the loading faster.
* '''image_mod''': modify the image path function ([[ImagePathFunctionWML]]) of all the unit's frames.
** '''replace''': replaces the image path function(s) to be used, e.g. "RC(magenta>red)"
** '''add''': adds an image path function without removing any existing ones.
* '''ellipse''': Change the image used for the unit's ellipse.
**'''ellipse''' : the new image to use.
* {{DevFeature1.11}} '''halo''': Change the image used for the unit's halo.
**'''halo''': the new image to use.
* {{DevFeature1.11}} '''overlay''': Change the unit's overlays.
**'''add''': the specified overlay will be added to the unit's overlays. It can be a comma separated list with multiple overlays. ''Note: overlays added in this way cannot be removed by [remove_unit_overlay] until the effect's duration is over.''
**'''replace''': all the unit's overlays will be removed and replaced with the specified one. Again, it can be a comma separated list. ''Note: overlays replaced in this way cannot be modified by [unit_overlay] or [remove_unit_overlay] until the effect's duration is over.''

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]
* [[AnimationWML]]

[[Category: WML Reference]]

DirectActionsWML

2012-08-04T18:28:09Z

Anonymissimus: /* [unstore_unit] */

{{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; 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.
* '''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''': {{DevFeature1.11}} 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]].

=== [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. The unit is recalled free of charge, and is placed near the leader.
* [[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.
* '''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.

=== [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]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [gold][filter_side] is deprecated, use the new inline 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
* '''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''': {{DevFeature1.11}} (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. Such units will be automatically hit (and killed) in combat, but if given the chance to heal, they will have a minimum of one hit point after healing (regardless of how negative their hit points were). This is unusual-looking behavior, so often should be avoided.

=== [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]] {{DevFeature1.11}} 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.
* '''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]] {{DevFeature1.11}} 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]] {{DevFeature1.11}} 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''': {{DevFeature1.11}} 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]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''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''': {{DevFeature1.11}} 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''': {{DevFeature1.11}} 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].

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

=== [modify_ai] ===
Changes AI objects (aspects, goals, candidate actions or stages) for a specified side. See [[AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag|AiWML]] 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]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [modify_ai][filter_side] is deprecated, use the new inline 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. Can add traits with immediate effect. 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 hitpoints, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned.
* [[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 and removes all items on the tile the unit is on.
* '''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 level. In a campaign objects with the same id can be assigned once per level.
* '''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 'level', 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). {{DevFeature1.11}} 'level' has been renamed to 'scenario'.
**if 'forever' or not set, effects never wear off.
** {{DevFeature1.11}} if 'turn', effects only last until the start of the units 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.)
* '''[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".
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.

* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.

=== [remove_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] ===
{{DevFeature1.11}}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] ===
{{DevFeature1.11}}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] ===
Allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move 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 move the first time.

=== [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 an 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.
* '''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.
* '''[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 an harmer, experience will be attributed like in regular combat.
* '''resistance_multiplier''': {{DevFeature1.11}} 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.

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

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.

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

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

DirectActionsWML

2012-08-04T18:27:14Z

Anonymissimus: /* [unstore_unit] */ document [unstore_unit]animate=

{{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; 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.
* '''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''': {{DevFeature1.11}} 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]].

=== [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. The unit is recalled free of charge, and is placed near the leader.
* [[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.
* '''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.

=== [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]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [gold][filter_side] is deprecated, use the new inline 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
* '''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. Such units will be automatically hit (and killed) in combat, but if given the chance to heal, they will have a minimum of one hit point after healing (regardless of how negative their hit points were). This is unusual-looking behavior, so often should be avoided.

=== [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]] {{DevFeature1.11}} 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.
* '''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]] {{DevFeature1.11}} 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]] {{DevFeature1.11}} 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''': {{DevFeature1.11}} 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]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''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''': {{DevFeature1.11}} 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''': {{DevFeature1.11}} 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].

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

=== [modify_ai] ===
Changes AI objects (aspects, goals, candidate actions or stages) for a specified side. See [[AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag|AiWML]] 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]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [modify_ai][filter_side] is deprecated, use the new inline 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. Can add traits with immediate effect. 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 hitpoints, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned.
* [[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 and removes all items on the tile the unit is on.
* '''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 level. In a campaign objects with the same id can be assigned once per level.
* '''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 'level', 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). {{DevFeature1.11}} 'level' has been renamed to 'scenario'.
**if 'forever' or not set, effects never wear off.
** {{DevFeature1.11}} if 'turn', effects only last until the start of the units 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.)
* '''[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".
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.

* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.

=== [remove_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] ===
{{DevFeature1.11}}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] ===
{{DevFeature1.11}}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] ===
Allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move 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 move the first time.

=== [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 an 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.
* '''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.
* '''[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 an harmer, experience will be attributed like in regular combat.
* '''resistance_multiplier''': {{DevFeature1.11}} 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.

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

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.

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

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

DirectActionsWML

2012-07-24T17:24:33Z

Anonymissimus: /* [modify_unit] */ correct trait adding example

{{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; 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.
* '''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''': {{DevFeature1.11}} 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]].

=== [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. The unit is recalled free of charge, and is placed near the leader.
* [[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.
* '''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.

=== [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]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [gold][filter_side] is deprecated, use the new inline 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
* '''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.
* '''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. Such units will be automatically hit (and killed) in combat, but if given the chance to heal, they will have a minimum of one hit point after healing (regardless of how negative their hit points were). This is unusual-looking behavior, so often should be avoided.

=== [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]] {{DevFeature1.11}} 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.
* '''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]] {{DevFeature1.11}} 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]] {{DevFeature1.11}} 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''': {{DevFeature1.11}} 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]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''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''': {{DevFeature1.11}} 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''': {{DevFeature1.11}} 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].

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

=== [modify_ai] ===
Changes AI objects (aspects, goals, candidate actions or stages) for a specified side. See [[AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag|AiWML]] 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]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [modify_ai][filter_side] is deprecated, use the new inline 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. Can add traits with immediate effect. 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 hitpoints, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned.
* [[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 and removes all items on the tile the unit is on.
* '''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 level. In a campaign objects with the same id can be assigned once per level.
* '''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 'level', 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). {{DevFeature1.11}} 'level' has been renamed to 'scenario'.
**if 'forever' or not set, effects never wear off.
** {{DevFeature1.11}} if 'turn', effects only last until the start of the units 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.)
* '''[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".
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.

* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.

=== [remove_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] ===
{{DevFeature1.11}}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] ===
{{DevFeature1.11}}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] ===
Allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move 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 move the first time.

=== [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 an 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.
* '''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.
* '''[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 an harmer, experience will be attributed like in regular combat.
* '''resistance_multiplier''': {{DevFeature1.11}} 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.

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

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.

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

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

2012-07-05T13:08:27Z

Anonymissimus: /* [store_time_of_day] */

{{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 dollars 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. '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. See [[BuildingMultiplayerExamples]] for more info on the MP case.

* '''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 comma) of the referenced variable.

* '''fpart''': Assigns the decimal part (the part to the right of the comma) 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

=== 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. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden', 'user_team_name', 'color', 'controller', 'village_gold', 'recruit', and 'side' (the $side_number of the side belonging to this container).

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

''note: In networked multiplayer, the controller attribute is ambiguous. Be very careful or you have OOS errors.''

==== [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. Time areas matter, illumination does not.

* '''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 [[InternalActionsWMLUnitTags|here]]. 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).

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

==== [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: The only advantage/difference this tag has, in comparison to using [store_locations]terrain=*^V*, is that the amount of hexes which are considered for a possible match is previously restricted to those with villages.

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

==== [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]
length = 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.
hexes = in 1.11, this will replace the length key above
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]
To read the total length of the path on 1.10, use ''path.step.length''. 
{{DevFeature1.11}} ''length'' is replaced by ''hexes'' in the output array.

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

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

* '''name''': the name of event to trigger

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

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

* [[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.

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

InterfaceActionsWML

2012-04-09T19:56:14Z

Anonymissimus: /* [item] */ document [item]redraw=

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

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

== [inspect] ==
This user interface action only works in debug mode. It displays the gamestate inspector dialog (the same one which can be brought up with '':inspect'' ), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

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

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

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

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

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown.
* '''image''': (default: profile image of speaker) the image to display next to the message.
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''duration''': (default: 10) the minimum number of frames for this message to be displayed. (A frame lasts about 30 milliseconds.) During this time any dialog decisions will be disregarded.
* '''sound''': a sound effect (wav file) to play as the message is displayed. This can be a comma-separated list, from which one will be randomly chosen.
* '''[option]''': No '''[option]''' elements have to be used. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option.
** '''message''': (translatable) the text displayed for the option (see [[DescriptionWML]])
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[InternalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message.
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
In 1.8, [http://developer.gnome.org/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes] have been adopted for '''[message]'''. These can also be used in unit names (user_description), objectives, and such. Note that you'll probably want to use a single quote ' instead of a double quote " as double quotes cannot be escaped, otherwise the string will appear fragmented and you may also encounter errors. Running wmllint on your campaign will up-convert it, warning you about unusual cases you must fix by hand.

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

<nowiki>You are victorious!</nowiki>

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

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

In 1.6, Wesnoth uses older text formatting options
* A tilde (~) as the first character causes the line to be boldfaced.
* An at symbol (@) as the first character causes the line to be green, as done with victory conditions.
* A pound symbol (#) as the first character causes the line to be red, as done with defeat conditions.
* An asterisk (*) as the first character causes the line to be bigger.
* A backquote (`) as the first character causes the line to be smaller.
* If used, the caption key text is boldfaced.
* An RGB colour code in the beginning causes the line to be the given colour. This can still be preceded by the above characters. Example: ''message=_"<255,0,0>Red!"''

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

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

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

=== Macros ===
There are a few predefined macros for Objectives that you can use to shorten the code: [http://www.wesnoth.org/macro-reference.xhtml#SET_OBJECTIVES SET_OBJECTIVES], [http://www.wesnoth.org/macro-reference.xhtml#VICTORY_CONDITION VICTORY_CONDITION], and [http://www.wesnoth.org/macro-reference.xhtml#DEFEAT_CONDITION DEFEAT_CONDITION]. Follow the links for each one to see complete syntax and example usage.

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu.

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item.
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it false.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a location filter similar to the one found inside Single Unit Filters (see [[FilterWML]]). The menu item will only be available on matching locations.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.
** '''delayed_variable_substitution ''' {{DevFeature1.11}} (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==
{{DevFeature1.11}}

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

== Other interface tags ==

The following tags are also action tags:
=== [item] ===
Makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros))''</tt>
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex.
* '''halo''': an image to place centered on the hex. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image. ''Example (where the integer after the colon is the duration of each frame): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': {{DevFeature1.11}}(boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items off
* '''image''' if specified, only removes the given image item (This image name must include any [[ImagePathFunctionWML|image path functions]] appended to the original image name.)

=== [print] ===
Displays a message across the screen. The message will disappear after a certain time.
* '''text''': (translatable) the text to display.
* '''size''': (default=12) the pointsize of the font to use
* '''duration''': (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255.
=== [move_unit_fake] ===
Moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
* '''type''': the type of the unit whose image to use
* '''x''': a comma-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctionWML|image path functions]] sequence to be applied on the fake unit.
=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''skip_steps''': the number of steps to skip before this unit starts moving
=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

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

=== [scroll] ===
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
* '''x''', '''y''': the number of pixels to scroll along the x and y axis
=== '''[scroll_to]''' ===
Scroll to a given hex
* '''x''', '''y''': the hex to scroll to
* {{DevFeature1.11}} [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.

=== [scroll_to_unit] ===
Scroll to a given unit
* [[StandardUnitFilter]]
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

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

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

=== [music]===
Switches to playing different music
* '''name''': the filename of the music to play (in ''music/'' as .ogg)
* see [[MusicListWML]] for the correct syntax
===[volume]===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.
=== [color_adjust]===
Tints the color of the screen.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color
=== [delay] ===
Pauses the game.
* '''time''': the time to pause in milliseconds
=== [redraw] ===
Redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
* '''clear_shroud''' (boolean yes|no, default no): If yes, recalculates fog and shroud. Useful if you for example spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), recalculates fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units
* '''image''': the image to remove from the unit

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

=== [label] ===
Places a label on the map.
* '''x''', '''y''': the location of the label
* '''text''': what the label should say
* '''team_name''': if specified, the label will only be visible to the given team.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.
* '''text''': the text to display.

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

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

=== [deprecated_message] ===
Shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.
* '''message''': the message to show.
=== [wml_message] ===
Outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
* '''message''': the message to show.
* '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

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

=== [chat] ===
Displays a message in the chat area.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

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

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

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

DirectActionsWML

2012-03-29T14:15:27Z

Anonymissimus: /* [object] */ clean and improve [object] documentation

{{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; 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.
* '''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''': {{DevFeature1.11}} 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]].

=== [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. The unit is recalled free of charge, and is placed near the leader.
* [[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.
* '''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.

=== [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]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [gold][filter_side] is deprecated, use the new inline 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
* '''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.
* '''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. Such units will be automatically hit (and killed) in combat, but if given the chance to heal, they will have a minimum of one hit point after healing (regardless of how negative their hit points were). This is unusual-looking behavior, so often should be avoided.

=== [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]] {{DevFeature1.11}} 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.
* '''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]] {{DevFeature1.11}} 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]] {{DevFeature1.11}} 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''': {{DevFeature1.11}} 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]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''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.
* '''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].

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

=== [modify_ai] ===
Changes AI objects (aspects, goals, candidate actions or stages) for a specified side. See [[AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag|AiWML]] 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]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [modify_ai][filter_side] is deprecated, use the new inline 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. Can add traits with immediate effect. 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]
type=Troll Rocklobber
[/filter]
hitpoints=10
[modifications]
[trait]
# first trait is unmodified
[/trait]
{TRAIT_HEALTHY}# second trait is replaced with the healthy trait
[/modifications]
[/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 hitpoints, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned.
* [[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 and removes all items on the tile the unit is on.
* '''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 level. In a campaign objects with the same id can be assigned once per level.
* '''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 'level', 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).
* '''[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 '''[removeitem]''' 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".
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.

* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.

=== [remove_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] ===
{{DevFeature1.11}}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. This is not shared with allies (even if share_view=yes), but multiple sides can be specified at once. The fog will remain cleared from these hexes until canceled by [reset_fog].
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the tiles from which fog should be lifted.

=== [reset_fog] ===
{{DevFeature1.11}}Cancels the effects of an earlier invocation of [lift_fog], causing fog to reset to what it would have been had WML not interfered. (That is, hexes that a side's units could not see this turn will be re-fogged, while other hexes remain unchanged.)
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the fog reset will be restricted to these tiles.
Omitting both the SSF and the SLF would cancel all earlier uses of [lift_fog].

=== [allow_undo] ===
Allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move 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 move the first time.

=== [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 an 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.
* '''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.
* '''[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 an harmer, experience will be attributed like in regular combat.
* '''resistance_multiplier''': {{DevFeature1.11}} 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.

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

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.

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

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

FilterWML

2012-03-28T15:05:28Z

Anonymissimus: /* Filtering Vision */ update a redundant section about filter_vision

{{WML Tags}}
== Filtering in WML ==

A ''filter'' is a special WML block.
Filters are used to describe a set of units, hexes, weapons or something else.
Filters are defined as matching something if all the keys in the filter match that thing.
For example, if a unit filter contains two keys,
a unit must match both of the keys in order to match the filter.

A StandardUnit(Location, Side, ...)Filter is the place where the set of such keys and tags can appear. A StandardFilter sometimes needs an according surrounding tag but often doesn't. It should be mentioned at the place in the wiki where it's said that you can use at a certain code position a StandardFilter whether you need a surrounding tag or not.

== Filtering Units ==

Filters are often used in action tags (see [[EventWML]]).
In this case the phrase "standard unit filter" is used in place of the set of standard keys.
Sometimes a filter is used to find the first unit that matches the filter;
for example, the '''[recall]''' tag recalls that unit.

Standard unit filters are also used in the tags '''[filter]''' and '''[filter_second]'''.
These are subtags of '''[event]''' which describe when the event should trigger.
Most event names (see [[EventWML]]) have units related to them called "primary unit" and "secondary unit".
In order for an event to be triggered, ''primary unit'' must match the filter contained in '''[filter]''',
and ''secondary unit'' must match the filter contained in '''[filter_second]'''.

See [[StandardUnitFilter]] for details.

== Filtering Locations ==

As you have seen, standard unit filter can contain a location filter.
Several actions, such as '''[terrain]''', also use location filters.
Location filters are represented on this site by the phrase "standard location filter".

See [[StandardLocationFilter]] for details.

== Filtering Sides ==
Sometimes, it's needed to get a list of sides which satisfy certain criteria. For this, a side filter can be used.
Side filters are represented on this site by the phrase "standard side filter".

See [[StandardSideFilter]] for details.

== Filtering Weapons ==

Sometimes weapons are filtered on in WML. See also [[EventWML]], [[EffectWML]], [[AnimationWML]].

These keys are used as filter input for weapon filters.

* '''range''': a range to filter
** '''melee''': only melee weapons pass
** '''ranged''': only ranged weapons pass
* '''name''': filter on the attack's name.
See '''data/units/''' or http://www.wesnoth.org/units/
to find the name of a particular unit's attack.
* '''type''': filter on the attack's type.
Values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'arcane'.
* '''damage''': filter on damage value. Can be a specific number or a list of ranges like 'damage=0-5,7-99'
* '''special''': filter on the attack's special power.
For values see [[AbilitiesWML]].

== Filtering Terrains ==

''This section describes basically the same as "Filtering Locations" above, namely a [[StandardLocationFilter]].''

Use '''[filter_location]''' within '''[filter]''' , for example:

[event]
[filter]
[filter_location]
terrain=Ch
[/filter_location]
[/filter]
[/event]

At some places the terrains can be filtered with a
match list. The list is a comma separated list and matching will stop
at the first matched [[TerrainCodesWML|terrain string]]. There's one special character
''!'' which inverts the meaning of a match. Terrain strings can
use the wildcard * to match zero or more following letters, characters
behind the * are not allowed and the result is undefined.

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

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

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

== Filtering Vision ==

The '''[filter_vision]''' tag allows you to filter locations based on whether or not the hex is obscured by fog or shroud from the point-of-view of a viewing side.

* '''visible''':
** '''yes''' (default): matches when the location is not obscured by fog or shroud for the ''viewing_side''
** '''no''': matches when the location is obscured by fog or shroud for the ''viewing_side''
* '''viewing_side''': the observing side, or list of observing sides
** When multiple viewing sides are listed, all of the sides must pass the visibility check in order for the [filter_vision] filter to return a successful match.
** When no viewing sides are listed, all enemy sides must pass the visibility check.
*'''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys; all matching sides must be able to see the unit/location. If an empty filter, all sides (instead of only all enemy sides) match. viewing_side= is renamed to just the [[StandardSideFilter]]'s side=.

'''Example:''' This event will fire when the enemy (side 2) moves to a location within the player's field of vision:
[event]
name=moveto
first_time_only=yes
[filter]
side=2
[filter_vision]
viewing_side=1
[/filter_vision]
[/filter]
[message]
speaker=unit
message="I am your enemy. I know that you can see me here."
[/message]
[/event]

'''Note:''' This filter is only useful when the viewing side is under a fog or shroud. You ''can'' set a shroud over an AI side. This will allow you to use the vision filter from the point-of-view of an AI side. The fog/shroud does not currently affect AI movement patterns, but the AI algorithm may become constrained by fog/shroud in the future.

== See Also ==

* [[UnitTypeWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

LuaWML/Pathfinder

2012-03-17T18:09:50Z

Anonymissimus: /* wesnoth.find_vacant_tile */ adapt find_vacant_tile docu for changes I made in r48649

This page describes the [[LuaWML]] functions and helpers for finding paths.

==== wesnoth.find_path ====

Returns the shortest path from one location to another. The source location is given either by coordinates as two arguments x and y; there must be a unit at the source location when using the standard path calculator. The source location can also be given by a unit as a single argument (as returned by the functions from [[LuaWML:Units]]). The second location is given by its coordinates. The last argument is an optional table that can be used to parametrize the pathfinder. Its options are:
* '''max_cost''': if set, the pathfinder will ignore paths longer than its value
* '''ignore_units''': if set, the path will go through units and ignore zones of control
* '''ignore_teleport''': if set, the teleport ability of the unit is ignored
* '''viewing_side''': if set to a valid side number, fog and shroud for this side will be taken into account; if set to an invalid number (e.g. 0), fog and shroud will be ignored; if left unset, the viewing side will be the unit side

The path is returned as a table of coordinate pairs. It contains both the source and destination tile if a path was found. The total cost of the path is also available as a second return value, if needed.

-- Display some items along the path from (x1,y1) to (x2,y2).
local u = wesnoth.get_units({ x = x1, y = y1 })[1]
local path, cost = wesnoth.find_path(u, x2, y2, { ignore_units = true, viewing_side = 0 })
if cost > u.moves then
wesnoth.message("That's too far!")
else
for i, loc in ipairs(path) do
wesnoth.fire("item", { x = loc[1], y = loc[2], image = "items/buckler.png" })
end
end

Instead of a parameter table, a cost function can be passed to the pathfinder. It will be called for all the tiles the computed path may possibly go through. It receives three arguments. The first two are the coordinates of the tile, the last one is the current cost for reaching that tile. The function should return a floating-point value that is the cost for entering the given tile. This cost should be greater or equal to one.

-- Count how many turns it would take, assuming the worst case (3 movement points per tile)
local max_moves = wesnoth.get_units({ x = x1, y = y1 })[1].max_moves
local path, cost = wesnoth.find_path(x1, y2, x2, y2,
function(x, y, current_cost)
local remaining_moves = max_moves - (current_cost % max_moves)
if remaining_moves < 3 then current_cost = current_cost + remaining_moves end
return current_cost + 3
end)
wesnoth.message(string.format("It would take %d turns.", math.ceil(cost / 3)))

==== wesnoth.find_vacant_tile ====

Returns the two coordinates of an empty tile the closest to the tile passed by coordinates. An optional unit (either a WML table or a proxy object) can be passed as a third argument; if so, the returned tile has terrain which is passable for the passed unit.

function teleport(src_x, src_y, dst_x, dst_y)
local u = wesnoth.get_units({x = src_x, y = src_y })[1]
local ut = u.__cfg
dst_x, dst_y = wesnoth.find_vacant_tile(dst_x, dst_y, u)
wesnoth.put_unit(src_x, src_y)
wesnoth.put_unit(dst_x, dst_y, ut)
end

==== wesnoth.find_reach ====

Returns all the locations reachable by a unit. The unit is given either by its two coordinates or by a proxy object. The last argument is an optional table that can be used to parametrize the pathfinder. Its options are:
* '''additional_turns''': if set to an integer n, the pathfinder will consider tiles that can be reached in n+1 turns
* '''ignore_units''': if set, the paths will go through units and ignore zones of control
* '''ignore_teleport''': if set, the teleport ability of the unit is ignored
* '''viewing_side''': if set to a valid side number, fog and shroud for this side will be taken into account; if set to an invalid number (e.g. 0), fog and shroud will be ignored; if left unset, the viewing side will be the unit side
The locations are stored as triples in an array. The first two elements of a triple are the coordinates of a reachable tile, the third one is the number of movement points left when reaching the tile.

-- overlay the number of turns needed to reach each tile
local t = wesnoth.find_reach(u, { additional_turns = 8 })
local m = u.max_moves
for i,l in ipairs(t) do
wesnoth.fire("label", { x = l[1], y = l[2], text = math.ceil(9 - l[3]/m) })
end

==== helper.distance_between ====

Returns the distance between two tiles given by their coordinates.

local d = distance_between(x1, y1, x2, y2)

==== helper.adjacent_tiles ====

Returns an iterator on the (at most six) tiles around a given location that are on the map. If the third argument is ''true'', tiles on the map border are also visited.

-- remove all the units next to the (a,b) tile
for x, y in helper.adjacent_tiles(a, b) do
wesnoth.put_unit(x, y)
end

[[Category: Lua Reference]]

InterfaceActionsWML

2012-03-07T20:03:23Z

Anonymissimus: /* [show_objectives] */ document SSF in show_objectives

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

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

== [inspect] ==
This user interface action only works in debug mode. It displays the gamestate inspector dialog (the same one which can be brought up with '':inspect'' ), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

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

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

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

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

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown.
* '''image''': (default: profile image of speaker) the image to display next to the message.
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''duration''': (default: 10) the minimum number of frames for this message to be displayed. (A frame lasts about 30 milliseconds.) During this time any dialog decisions will be disregarded.
* '''sound''': a sound effect (wav file) to play as the message is displayed. This can be a comma-separated list, from which one will be randomly chosen.
* '''[option]''': No '''[option]''' elements have to be used. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option.
** '''message''': (translatable) the text displayed for the option (see [[DescriptionWML]])
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[InternalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message.
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
In 1.8, [http://developer.gnome.org/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes] have been adopted for '''[message]'''. These can also be used in unit names (user_description), objectives, and such. Note that you'll probably want to use a single quote ' instead of a double quote " as double quotes cannot be escaped, otherwise the string will appear fragmented and you may also encounter errors. Running wmllint on your campaign will up-convert it, warning you about unusual cases you must fix by hand.

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

<nowiki>You are victorious!</nowiki>

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

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

In 1.6, Wesnoth uses older text formatting options
* A tilde (~) as the first character causes the line to be boldfaced.
* An at symbol (@) as the first character causes the line to be green, as done with victory conditions.
* A pound symbol (#) as the first character causes the line to be red, as done with defeat conditions.
* An asterisk (*) as the first character causes the line to be bigger.
* A backquote (`) as the first character causes the line to be smaller.
* If used, the caption key text is boldfaced.
* An RGB colour code in the beginning causes the line to be the given colour. This can still be preceded by the above characters. Example: ''message=_"<255,0,0>Red!"''

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

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

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

=== Macros ===
There are a few predefined macros for Objectives that you can use to shorten the code: [http://www.wesnoth.org/macro-reference.xhtml#SET_OBJECTIVES SET_OBJECTIVES], [http://www.wesnoth.org/macro-reference.xhtml#VICTORY_CONDITION VICTORY_CONDITION], and [http://www.wesnoth.org/macro-reference.xhtml#DEFEAT_CONDITION DEFEAT_CONDITION]. Follow the links for each one to see complete syntax and example usage.

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu.

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item.
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it false.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a location filter similar to the one found inside Single Unit Filters (see [[FilterWML]]). The menu item will only be available on matching locations.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.
** '''delayed_variable_substitution ''' {{DevFeature1.11}} (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==
{{DevFeature1.11}}

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

== Other interface tags ==

The following tags are also action tags:
=== [item] ===
Makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros))''</tt>
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex.
* '''halo''': an image to place centered on the hex. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image. ''Example (where the integer after the colon is the duration of each frame): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items off
* '''image''' if specified, only removes the given image item (This image name must include any [[ImagePathFunctionWML|image path functions]] appended to the original image name.)

=== [print] ===
Displays a message across the screen. The message will disappear after a certain time.
* '''text''': (translatable) the text to display.
* '''size''': (default=12) the pointsize of the font to use
* '''duration''': (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255.
=== [move_unit_fake] ===
Moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
* '''type''': the type of the unit whose image to use
* '''x''': a comma-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctionWML|image path functions]] sequence to be applied on the fake unit.
=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''skip_steps''': the number of steps to skip before this unit starts moving
=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

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

=== [scroll] ===
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
* '''x''', '''y''': the number of pixels to scroll along the x and y axis
=== '''[scroll_to]''' ===
Scroll to a given hex
* '''x''', '''y''': the hex to scroll to
* {{DevFeature1.11}} [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.

=== [scroll_to_unit] ===
Scroll to a given unit
* [[StandardUnitFilter]]
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

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

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

=== [music]===
Switches to playing different music
* '''name''': the filename of the music to play (in ''music/'' as .ogg)
* see [[MusicListWML]] for the correct syntax
===[volume]===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.
=== [color_adjust]===
Tints the color of the screen.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color
=== [delay] ===
Pauses the game.
* '''time''': the time to pause in milliseconds
=== [redraw] ===
Redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
* '''clear_shroud''' (boolean yes|no, default no): If yes, recalculates fog and shroud. Useful if you for example spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), recalculates fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units
* '''image''': the image to remove from the unit

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

=== [label] ===
Places a label on the map.
* '''x''', '''y''': the location of the label
* '''text''': what the label should say
* '''team_name''': if specified, the label will only be visible to the given team.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.
* '''text''': the text to display.

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

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

=== [deprecated_message] ===
Shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.
* '''message''': the message to show.
=== [wml_message] ===
Outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
* '''message''': the message to show.
* '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

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

=== [chat] ===
Displays a message in the chat area.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

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

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

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

InterfaceActionsWML

2012-03-07T19:51:15Z

Anonymissimus: /* [objectives] */ document inline SSF in [objectives]

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

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

== [inspect] ==
This user interface action only works in debug mode. It displays the gamestate inspector dialog (the same one which can be brought up with '':inspect'' ), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

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

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

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

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

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown.
* '''image''': (default: profile image of speaker) the image to display next to the message.
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''duration''': (default: 10) the minimum number of frames for this message to be displayed. (A frame lasts about 30 milliseconds.) During this time any dialog decisions will be disregarded.
* '''sound''': a sound effect (wav file) to play as the message is displayed. This can be a comma-separated list, from which one will be randomly chosen.
* '''[option]''': No '''[option]''' elements have to be used. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option.
** '''message''': (translatable) the text displayed for the option (see [[DescriptionWML]])
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[InternalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message.
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
In 1.8, [http://developer.gnome.org/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes] have been adopted for '''[message]'''. These can also be used in unit names (user_description), objectives, and such. Note that you'll probably want to use a single quote ' instead of a double quote " as double quotes cannot be escaped, otherwise the string will appear fragmented and you may also encounter errors. Running wmllint on your campaign will up-convert it, warning you about unusual cases you must fix by hand.

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

<nowiki>You are victorious!</nowiki>

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

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

In 1.6, Wesnoth uses older text formatting options
* A tilde (~) as the first character causes the line to be boldfaced.
* An at symbol (@) as the first character causes the line to be green, as done with victory conditions.
* A pound symbol (#) as the first character causes the line to be red, as done with defeat conditions.
* An asterisk (*) as the first character causes the line to be bigger.
* A backquote (`) as the first character causes the line to be smaller.
* If used, the caption key text is boldfaced.
* An RGB colour code in the beginning causes the line to be the given colour. This can still be preceded by the above characters. Example: ''message=_"<255,0,0>Red!"''

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

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

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

=== Macros ===
There are a few predefined macros for Objectives that you can use to shorten the code: [http://www.wesnoth.org/macro-reference.xhtml#SET_OBJECTIVES SET_OBJECTIVES], [http://www.wesnoth.org/macro-reference.xhtml#VICTORY_CONDITION VICTORY_CONDITION], and [http://www.wesnoth.org/macro-reference.xhtml#DEFEAT_CONDITION DEFEAT_CONDITION]. Follow the links for each one to see complete syntax and example usage.

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu.

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item.
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it false.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a location filter similar to the one found inside Single Unit Filters (see [[FilterWML]]). The menu item will only be available on matching locations.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.
** '''delayed_variable_substitution ''' {{DevFeature1.11}} (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==
{{DevFeature1.11}}

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

== Other interface tags ==

The following tags are also action tags:
=== [item] ===
Makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros))''</tt>
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex.
* '''halo''': an image to place centered on the hex. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image. ''Example (where the integer after the colon is the duration of each frame): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items off
* '''image''' if specified, only removes the given image item (This image name must include any [[ImagePathFunctionWML|image path functions]] appended to the original image name.)

=== [print] ===
Displays a message across the screen. The message will disappear after a certain time.
* '''text''': (translatable) the text to display.
* '''size''': (default=12) the pointsize of the font to use
* '''duration''': (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255.
=== [move_unit_fake] ===
Moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
* '''type''': the type of the unit whose image to use
* '''x''': a comma-separated list of x locations to move along
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
* '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctionWML|image path functions]] sequence to be applied on the fake unit.
=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''skip_steps''': the number of steps to skip before this unit starts moving
=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

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

=== [scroll] ===
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
* '''x''', '''y''': the number of pixels to scroll along the x and y axis
=== '''[scroll_to]''' ===
Scroll to a given hex
* '''x''', '''y''': the hex to scroll to
* {{DevFeature1.11}} [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.

=== [scroll_to_unit] ===
Scroll to a given unit
* [[StandardUnitFilter]]
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

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

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

=== [music]===
Switches to playing different music
* '''name''': the filename of the music to play (in ''music/'' as .ogg)
* see [[MusicListWML]] for the correct syntax
===[volume]===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.
=== [color_adjust]===
Tints the color of the screen.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color
=== [delay] ===
Pauses the game.
* '''time''': the time to pause in milliseconds
=== [redraw] ===
Redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
* '''clear_shroud''' (boolean yes|no, default no): If yes, recalculates fog and shroud. Useful if you for example spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), recalculates fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units
* '''image''': the image to remove from the unit

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

=== [label] ===
Places a label on the map.
* '''x''', '''y''': the location of the label
* '''text''': what the label should say
* '''team_name''': if specified, the label will only be visible to the given team.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.
* '''text''': the text to display.

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

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

=== [deprecated_message] ===
Shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.
* '''message''': the message to show.
=== [wml_message] ===
Outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
* '''message''': the message to show.
* '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open
=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
=== [chat] ===
Displays a message in the chat area.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

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

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

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

DirectActionsWML

2012-02-25T15:08:57Z

Anonymissimus: /* [move_unit] */

{{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; 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.
* '''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''': {{DevFeature1.11}} 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]].

=== [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. The unit is recalled free of charge, and is placed near the leader.
* [[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.
* '''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.

=== [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]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [gold][filter_side] is deprecated, use the new inline 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
* '''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.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.

=== [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]] {{DevFeature1.11}} 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.
* '''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]] {{DevFeature1.11}} 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]] {{DevFeature1.11}} 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.
* '''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''': {{DevFeature1.11}} 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]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''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.
* '''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

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

=== [modify_ai] ===
* [[StandardSideFilter]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [modify_ai][filter_side] is deprecated, use the new inline SSF.
Changes the AI for a specified side. See [[Customizing_AI_in_Wesnoth_1.8#.5Bmodify_ai.5D_tag]]

=== [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. Can add traits with immediate effect. 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]
type=Troll Rocklobber
[/filter]
hitpoints=10
[modifications]
[trait]
# first trait is unmodified
[/trait]
{TRAIT_HEALTHY}# second trait is replaced with the healthy trait
[/modifications]
[/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 hitpoints, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned.
* [[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 and removes all items on the tile the unit is on.
* '''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 level. In a campaign objects with the same id can be assigned once per level.
* '''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 'level', 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).
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
* '''[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 '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''silent''': whether or not messages should be suppressed. Default is "no".
* '''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.
* If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
* The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.

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

=== [allow_undo] ===
Allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move 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 move the first time.

=== [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 an 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.
* '''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.
* '''[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 an harmer, experience will be attributed like in regular combat.
* '''resistance_multiplier''': {{DevFeature1.11}} 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.

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

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.

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

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

DirectActionsWML

2012-02-24T20:47:50Z

Anonymissimus: /* [unstore_unit] */ remove note about units always unstored with >= 1 hps; see https://gna.org/bugs/index.php?19324

{{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; 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.
* '''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''': {{DevFeature1.11}} 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]].

=== [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. The unit is recalled free of charge, and is placed near the leader.
* [[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.
* '''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.

=== [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]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [gold][filter_side] is deprecated, use the new inline 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
* '''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.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.

=== [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]] {{DevFeature1.11}} 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.
* '''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]] {{DevFeature1.11}} 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]] {{DevFeature1.11}} 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.
* '''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''': {{DevFeature1.11}} 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]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''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.
* '''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

=== [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 passable location is chosen. All target locations passed (see below) need to be passable hexes for the particular moved units.
* '''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.)

=== [modify_ai] ===
* [[StandardSideFilter]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [modify_ai][filter_side] is deprecated, use the new inline SSF.
Changes the AI for a specified side. See [[Customizing_AI_in_Wesnoth_1.8#.5Bmodify_ai.5D_tag]]

=== [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. Can add traits with immediate effect. 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]
type=Troll Rocklobber
[/filter]
hitpoints=10
[modifications]
[trait]
# first trait is unmodified
[/trait]
{TRAIT_HEALTHY}# second trait is replaced with the healthy trait
[/modifications]
[/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 hitpoints, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned.
* [[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 and removes all items on the tile the unit is on.
* '''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 level. In a campaign objects with the same id can be assigned once per level.
* '''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 'level', 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).
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
* '''[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 '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''silent''': whether or not messages should be suppressed. Default is "no".
* '''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.
* If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
* The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.

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

=== [allow_undo] ===
Allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move 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 move the first time.

=== [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 an 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.
* '''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.
* '''[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 an harmer, experience will be attributed like in regular combat.
* '''resistance_multiplier''': {{DevFeature1.11}} 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.

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

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.

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

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

StandardLocationFilter

2012-02-16T17:57:04Z

Anonymissimus:

{{WML Tags}}

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

The following attributes and sub-tags are permitted:

* '''time_of_day''': filter matches only on a given time of day (one of lawful, chaotic, neutral or liminal). Note: ''chaotic'', ''lawful'', ''neutral'' and ''liminal''; these are not times of day, these are ''alignments''. To match against 'dawn', 'dusk', 'first watch' etc., use the '''time_of_day_id''' key described below.
* '''time_of_day_id''': this accepts a list of one or more actual times of day, separated by commas. These IDs are taken from '''data/core/macros/schedules.cfg'''. Permissible values are case-sensitive: dawn, morning, afternoon, dusk, first_watch, second_watch, indoors, underground and deep_underground.
* '''terrain''': comma separated list of terrains. (See also: [http://www.wesnoth.org/wiki/FilterWML#Filtering_Terrains Filtering Terrains]).
* '''x,y''': the same as in the unit filter; supports any range ([http://www.wesnoth.org/wiki/StandardLocationFilter#Notes_about_Coordinate_Usage notes])
* '''[filter]''' with a [[StandardUnitFilter]] as argument; if present a unit must also be there
* '''owner_side''': If a valid side number, restricts stored locations to villages belonging to this side. If 0, restricts to all unowned locations (the whole map except villages which belong to some valid side). A hex is considered a village if and only if its [ [[TerrainWML|terrain_type]] ]gives_income= parameter was set to yes (which means a side can own that hex).
*'''[filter_owner]''': {{DevFeature1.11}}: If present, inline owner_side= is ignored. Restricts stored locations to villages, each of which must belong to any of the matching sides. If no sides match, restricts to unowned villages (and only these).
**'''[[StandardSideFilter]]''' tags and keys as arguments
* '''find_in''': name of an array or container variable; if present, the location will not match unless it is also found stored in the variable
* '''radius''': matches if any location within the radius matches this filter ([http://www.wesnoth.org/wiki/StandardLocationFilter#Notes_about_Radius_Usage notes])
* '''[filter_radius]''': a standard location filter; normally the radius extends outwards from matching locations one step at a time without checking any additional information-- however, if this tag is present, the radius will be restricted so that it can only expand outwards in the directions where it passes the given location filter
* '''[and]''': an extra location filter. Unless a location matches the [and] filter, then it will be excluded. ''Note: [and],[or],and [not] extra location filters are considered after everything else in the containing filter (except radius, which is considered last in 1.3.8 and greater); they are then processed in the order encountered.''
* '''[or]''': an extra location filter. If a location matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.
* '''[not]''': an extra location filter. If a location matches the [not] filter, then that location will be excluded.
* '''[filter_adjacent_location]''': a standard location filter; if present the correct number of adjacent locations must match this filter
** '''count''': a number, range, or comma separated range; default "1-6"
** '''adjacent''': a comma separated list of directions; default "n,ne,se,s,sw,nw"

==Notes about Coordinate Usage==
When specifying coordinates, the following keys are used:
* '''x''': the first coordinate
* '''y''': the second coordinate

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

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

Commas(''',''') are used to separate coordinates into a list.
The '''x''' and '''y''' lists are then paired up, with each pair representing one hex or range.

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

==Notes about Radius Usage==
:If you aren't storing any locations successfully, it may be because you put the radius or filters in the wrong place for them to combine correctly.
[have_location]
terrain=Gg^Vh
[and]
x=$x1
y=$y1
radius=1
[/and]
[/have_location]
Note that the use of [and] here causes the radius to have a very different meaning. Normally, all of the criteria besides radius are checked, producing a set of hexes to which the radius is applied. This means, for example, that if you're trying to find "a hex without a unit on it within 5 hexes of (15, 23)", the code:
[have_location]
x,y=15,23
radius=5
[not]
[filter]
[/filter]
[/not]
[have_location]
will not work! First, it looks for a hex with x=15, y=23 without a unit on it. Then, it returns that hex and all hexes within 5 of it. If (15, 23) happens to be occupied, then it will return no hexes, because "all hexes within 5 hexes of (no hexes)" is still "no hexes". Instead, put an [and] around the x,y and radius requirements, and it will separately find "(15, 23) and all hexes within 5 of it" and "each of those hexes that doesn't have a unit on it", producing the desired result.
[[Category: WML Reference]]

Template:WML Tags

2012-02-14T22:48:46Z

Anonymissimus:

{| class="gallery" style="width:225px;float: right;border: 1px solid #B48648; color:#B48648; font-size: 7pt;margin-left;10px;"
|-
|
[{{SERVER}}{{localurl:Template:WML Tags|action=edit}} edit ]
'''WML Tags'''

|-
|''A:''
[[AbilitiesWML|abilities]],
[[CampaignWML|about]],
[[AdvancedPreferenceWML|advanced_preference]],
[[UnitTypeWML|advancefrom]],
[[UnitTypeWML|advancement]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|advances]],
[[AiWML#the_.5Bai.5D_tag|ai]],
[[DirectActionsWML#.5Ballow_end_turn.5D|allow_end_turn]],
[[DirectActionsWML#.5Ballow_extra_recruit.5D|allow_extra_recruit]],
[[DirectActionsWML#.5Ballow_recruit.5D|allow_recruit]],
[[DirectActionsWML#.5Ballow_undo.5D|allow_undo]],
[[ConditionalActionsWML#Meta_Condition_Tags|and]],
[[InterfaceActionsWML#.5Banimate_unit.5D|animate_unit]],
[[AnimationWML|animation]],
[[VariablesWML#Array|array]],
[[UnitTypeWML#Attacks|attack]],
[[AnimationWML|attack_filter]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|attacks]],
[[AiWML#the_.5Bai.5D_tag|avoid]];
|-
|''B:''
[[UnitTypeWML#Other_tags|base_unit]], [[BinaryPathWML|binary_path]], [[HelpWML#Help_System_Topic_Markup|bold]], [[EditorWML#The_.5Bbrush.5D_tag|brush]];
|-
|''C:''
[[CampaignWML#The_.5Bcampaign.5D_tag|campaign]],
[[DirectActionsWML#.5Bcapture_village.5D|capture_village]],
[[ConditionalActionsWML#.5Bswitch.5D|case]],
[[InterfaceActionsWML#.5Bchat.5D|chat]],
[[ReplayWML|choose]],
[[PersistenceWML|clear_global_variable]],
[[InterfaceActionsWML#.5Bclear_menu_item.5D|clear_menu_item]],
[[InternalActionsWML|clear_variable]],
[[InterfaceActionsWML#.5Bcolour_adjust.5D|colour_adjust]],
command([[ConditionalActionsWML#.5Bcommand.5D|action]], [[ReplayWML|replay]]);
|-
|''D:''
[[AbilitiesWML|damage]],
[[StatisticalScenarioWML|deaths]],
[[AnimationWML|defend]],
[[StatisticalScenarioWML|defends]],
[[UnitTypeWML|defense]],
[[InterfaceActionsWML#.5Bdelay.5D|delay]],
[[InterfaceActionsWML#.5Bdeprecated_message.5D|deprecated_message]],
[[ReplayWML|destination]],
[[DirectActionsWML#.5Bdisallow_end_turn.5D|disallow_end_turn]],
[[DirectActionsWML#.5Bdisallow_extra_recruit.5D|disallow_extra_recruit]],
[[DirectActionsWML#.5Bdisallow_recruit.5D|disallow_recruit]],
[[ConditionalActionsWML#.5Bwhile.5D|do]];
|-
|''E:''
[[EditorWML|editor_group]],
[[EditorWML|editor_music]],
[[EditorWML|editor_times]],
[[EditorWML|editor_tool_hint]],
[[EffectWML|effect]],
else ([[ConditionalActionsWML#.5Bif.5D|action]], [[AnimationWML#.5Bif.5D_and_.5Belse.5D|animation]]),
[[DirectActionsWML#.5Bendlevel.5D|endlevel]],
end_turn ([[DirectActionsWML#.5Bend_turn.5D|action]], [[ReplayWML|replay]]),
[[EraWML|era]],
[[EventWML|event]],
[[ThemeWML|expenses]];
|-
|''F:''
[[EventWML#.5Bfilter.5D|filter]],
[[FilterWML|filter]],
[[AnimationWML|filter_attack]],
[[EventWML#.5Bfilter_attack.5D|filter_attack]],
[[EventWML#.5Bfilter_condition.5D|filter_condition]],
[[FilterWML|filter_location]],
[[EventWML#.5Bfilter_second.5D|filter_second]],
[[FilterWML|filter_second]],
[[AnimationWML|filter_second_attack]],
[[EventWML#.5Bfilter_second_attack.5D|filter_second_attack]],
[[EventWML#.5Bfilter_side.5D|filter_side]],
[[FilterWML#Filtering_Vision|filter_vision]],
[[StandardUnitFilter|filter_wml]],
[[InternalActionsWML#.5Bfind_path.5D|find_path]],
[[InternalActionsWML|fire_event]],
[[InterfaceActionsWML#.5Bfloating_text.5D|floating_text]],
[[HelpWML|format]],
[[AnimationWML|frame]];
|-
|''G:''
[[GameConfigWML|game_config]],
[[ScenarioWML|generator]],
[[PersistenceWML|get_global_variable]],
gold([[DirectActionsWML#.5Bgold.5D|action]], [[ThemeWML|theme]]);
|-
|''H:''
[[DirectActionsWML#.5Bharm_unit.5D|harm_unit]],
[[ConditionalActionsWML#Condition_Tags|have_location]],
[[ConditionalActionsWML#Condition_Tags|have_unit]],
[[HelpWML|header]],
[[DirectActionsWML#.5Bheal_unit.5D|heal_unit]],
[[UnitsWML|hide_help]],
[[InterfaceActionsWML#.5Bhide_unit.5D|hide_unit]];
|-
|''I:''
if ([[ConditionalActionsWML#.5Bif.5D|action]], [[AnimationWML#.5Bif.5D_and_.5Belse.5D|animation]]),
[[TerrainGraphicsWML|image]],
[[HelpWML|img]],
[[ThemeWML|income]],
[[ReplayWML|init_side]],
[[InternalActionsWML#.5Binsert_tag.5D|insert_tag]],
[[InterfaceActionsWML#.5Binspect.5D|inspect]],
[[HelpWML|italic]],
[[InterfaceActionsWML#.5Bitem.5D|item]];
|-
|''J:''
[[HelpWML|jump]],
[[InternalActionsWML|join]];
|-
|''K:''
[[DirectActionsWML#.5Bkill.5D|kill]],
[[StatisticalScenarioWML|killed]];
|-
|''L:''
label ([[InterfaceActionsWML#.5Blabel.5D|map]], [[ThemeWML|theme]]),
[[LanguageWML|language]],
[[AiWML|leader_goal]],
[[LocaleWML|locale]],
[[LuaWML|lua]];
|-
|''M:''
[[ThemeWML|main_map]],
[[ThemeWML|menu]],
[[InterfaceActionsWML#.5Bmessage.5D|message]],
[[ThemeWML|mini_map]],
[[AnimationWML|missile_frame]],
[[SingleUnitWML|modifications]],
[[DirectActionsWML#.5Bmodify_ai.5D|modify_ai]],
[[DirectActionsWML#.5Bmodify_side.5D|modify_side]],
[[DirectActionsWML#.5Bmodify_turns.5D|modify_turns]],
[[DirectActionsWML#.5Bmodify_unit.5D|modify_unit]],
[[ReplayWML|move]],
[[DirectActionsWML#.5Bmove_unit.5D|move_unit]],
[[InterfaceActionsWML#.5Bmove_unit_fake.5D|move_unit_fake]],
[[InterfaceActionsWML#.5Bmove_units_fake.5D|move_units_fake]],
[[UnitTypeWML|movement costs]],
[[UnitsWML|movetype]],
[[ScenarioWML|multiplayer]],
[[EraWML|multiplayer_side]],
[[MusicListWML#.5Bmusic.5D|music]];
|-
|''N:''
not ([[ConditionalActionsWML#Meta_Condition_Tags|condition]],
[[FilterWML|filter]]),
[[ThemeWML|num_units]];
|-
|''O:''
[[DirectActionsWML#.5Bobject.5D|object]],
[[InterfaceActionsWML#.5Bobjectives.5D|objectives]],
[[InterfaceActionsWML#.5Bobjectives.5D|objective]],
[[ThemeWML|observers]],
[[InterfaceActionsWML#.5Bopen_help.5D|open_help]],
[[InterfaceActionsWML|option]],
[[ConditionalActionsWML#Meta_Condition_Tags|or]];
|-
|''P:''
[[ThemeWML|panel]], [[IntroWML|part]], [[DirectActionsWML#.5Bpetrify.5D|petrify]], [[DirectActionsWML#.5Bplace_shroud.5D|place_shroud]], [[ThemeWML|position]],
[[InterfaceActionsWML#.5Bprint.5D|print]], [[AiWML|protect_location]], [[AiWML|protect_unit]];
|-
|''R:''
[[UnitsWML|race]], [[ReplayWML|random]], recall ([[DirectActionsWML#.5Brecall.5D|action]],
[[ReplayWML|replay]]), [[StatisticalScenarioWML|recalls]],
[[ReplayWML|recruit]], [[StatisticalScenarioWML|recruits]], [[InterfaceActionsWML#.5Bredraw.5D|redraw]],
[[HelpWML|ref]], [[DirectActionsWML|remove_shroud]], [[InterfaceActionsWML#.5Bremove_unit_overlay.5D|remove_unit_overlay]],
[[InterfaceActionsWML#.5Bremoveitem.5D|removeitem]], [[InterfaceActionsWML#.5Bremove_sound_source.5D|remove_sound_source]],
[[DirectActionsWML#.5Breplace_map.5D|replace_map]], [[DirectActionsWML#.5Breplace_schedule.5D|replace_schedule]], [[SavefileWML|replay]], [[SavefileWML|replay_start]],
[[UnitTypeWML|resistance]], [[ThemeWML|resolution]], [[ReplayWML|results]], [[InternalActionsWML|role]];
|-
|''S:''
[[SavefileWML|save]], [[ScenarioWML|scenario]],
[[InterfaceActionsWML#.5Bscroll.5D|scroll]], [[InterfaceActionsWML#.5Bscroll_to.5D|scroll_to]],
[[InterfaceActionsWML#.5Bscroll_to_unit.5D|scroll_to_unit]], [[AnimationWML|secondary_attack_filter]], [[AnimationWML|secondary_unit_filter]], [[HelpWML|section]], [[InterfaceActionsWML#.5Bselect_unit.5D|select_unit]], [[PersistenceWML|set_global_variable]],
[[InterfaceActionsWML#.5Bset_menu_item.5D|set_menu_item]], [[DirectActionsWML#.5Bset_recruit.5D|set_recruit]],
[[DirectActionsWML#.5Bset_extra_recruit.5D|set_extra_recruit]],
[[InternalActionsWML|set_variable]], [[InternalActionsWML|set_variables]], [[InterfaceActionsWML#.5Bshow_objectives.5D|show_objectives]],
[[SideWML|side]], [[ThemeWML|side_playing]], [[SavefileWML|snapshot]],
[[InterfaceActionsWML#.5Bsound.5D|sound]], [[InterfaceActionsWML#.5Bsound_source.5D|sound_source]], [[ReplayWML|source]],
[[InternalActionsWML|split]],
[[StatisticalScenarioWML#The_.5Bstatistics.5D_tag|statistics]],
status([[SingleUnitWML|single unit]], [[ThemeWML|theme]]), [[InternalActionsWML#.5Bstore_gold.5D|store_gold]],
[[InternalActionsWML#.5Bstore_items.5D|store_items]],
[[InternalActionsWML#.5Bstore_locations.5D|store_locations]],
[[InternalActionsWML#.5Bstore_map_dimensions.5D|store_map_dimensions]],
[[InternalActionsWML#.5Bstore_reachable_locations.5D|store_reachable_locations]],
[[InternalActionsWML#.5Bstore_side.5D|store_side]], [[InternalActionsWML#.5Bstore_starting_location.5D|store_starting_location]], [[InternalActionsWML#.5Bstore_time_of_day.5D|store_time_of_day]], [[InternalActionsWML#.5Bstore_unit.5D|store_unit]], [[InternalActionsWML#.5Bstore_unit_type.5D|store_unit_type]],
[[InternalActionsWML#.5Bstore_unit_type_ids.5D|store_unit_type_ids]],
[[InternalActionsWML#.5Bstore_villages.5D|store_villages]],[[IntroWML|story]],
[[ConditionalActionsWML#.5Bswitch.5D|switch]];
|-
|''T:''
[[AiWML|target]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|team]],
teleport ([[DirectActionsWML#.5Bteleport.5D|action]], [[AbilitiesWML|ability]]), [[AnimationWML|teleport_anim]],
[[DirectActionsWML#.5Bterrain.5D|terrain]], [[TerrainGraphicsWML|terrain_graphics]], [[TerrainMaskWML|terrain_mask]], [[TerrainWML|terrain_type]], [[ScenarioWML#Test_scenario|test]],
[[WesCamp#The_textdomain_declaration|textdomain]], [[InterfaceActionsWML|text_input]], [[ThemeWML|theme]], [[ConditionalActionsWML#.5Bif.5D|then]],
[[TerrainGraphicsWML|tile]], [[TimeWML|time]], time_area ([[DirectActionsWML#.5Btime_area.5D|action]], [[ScenarioWML|scenario]]),
[[ThemeWML|time_of_day]],
[[HelpWML|topic]], [[HelpWML|toplevel]], [[SingleUnitWML|trait]], [[DirectActionsWML#.5Btransform_unit.5D|transform_unit]], [[DirectActionsWML#.5Btunnel.5D|tunnel]], [[ThemeWML|turn]], [[ScenarioWML|tutorial]];
|-
|''U:''
[[InterfaceActionsWML#.5Bunhide_unit.5D|unhide_unit]], [[SingleUnitWML|unit]],
[[ThemeWML|unit_abilities]], [[ThemeWML|unit_alignment]], [[ThemeWML|unit_description]], [[AnimationWML|unit_filter]], [[ThemeWML|unit_hp]], [[ThemeWML|unit_image]], [[ThemeWML|unit_level]], [[ThemeWML|unit_moves]],
[[InterfaceActionsWML#.5Bunit_overlay.5D|unit_overlay]], [[ThemeWML|unit_profile]], [[ThemeWML|unit_status]],
[[ThemeWML|unit_traits]], [[UnitTypeWML|unit_type]], [[ThemeWML|unit_weapons]], [[ThemeWML|unit_xp]],
[[UnitsWML|units]], [[DirectActionsWML#.5Bunpetrify.5D|unpetrify]], [[DirectActionsWML#.5Bunstore_unit.5D|unstore_unit]], [[ThemeWML|upkeep]];
|-
| ''V:''
[[ConditionalActionsWML#Condition_Tags|variable]],
[[VariablesWML|variables]],
[[SideWML|village]],
[[ThemeWML|villages]],
[[InterfaceActionsWML#.5Bvolume.5D|volume]];
|-
| ''W:''
[[ConditionalActionsWML#.5Bwhile.5D|while]],
[[InterfaceActionsWML#.5Bwml_message.5D|wml_message]];
|}

<includeonly>[[Category:WML Reference]]</includeonly>

<noinclude>A box with all the WML tags, each one linking to the page and section they are described in. This box should be included in each of the WML reference pages.</noinclude>

StandardLocationFilter

2012-02-14T22:23:32Z

Anonymissimus:

{{WML Tags}}

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

The following attributes and sub-tags are permitted:

* '''time_of_day''': filter matches only on a given time of day (one of lawful, chaotic, neutral or liminal). Note: ''chaotic'', ''lawful'', ''neutral'' and ''liminal''; these are not times of day, these are ''alignments''. To match against 'dawn', 'dusk', 'first watch' etc., use the '''time_of_day_id''' key described below.
* '''time_of_day_id''': this accepts a list of one or more actual times of day, separated by commas. These IDs are taken from '''data/core/macros/schedules.cfg'''. Permissible values are case-sensitive: dawn, morning, afternoon, dusk, first_watch, second_watch, indoors, underground and deep_underground.
* '''terrain''': comma separated list of terrains. (See also: [http://www.wesnoth.org/wiki/FilterWML#Filtering_Terrains Filtering Terrains]).
* '''x,y''': the same as in the unit filter; supports any range ([http://www.wesnoth.org/wiki/StandardLocationFilter#Notes_about_Coordinate_Usage notes])
* '''[filter]''' with a [[StandardUnitFilter]] as argument; if present a unit must also be there
* '''owner_side''': If a valid side number, restricts stored locations to villages belonging to this side. If 0, restricts to all unowned locations (the whole map except villages which belong to some valid side). A hex is considered a village if and only if its [ [[TerrainWML|terrain_type]] ]gives_income= parameter was set to yes (which means a side can own that hex).
*'''[filter_side]''': {{DevFeature1.11}}: If present, inline owner_side= is ignored. Restricts stored locations to villages, each of which must belong to any of the matching sides. If no sides match, restricts to unowned villages (and only these).
**'''[[StandardSideFilter]]''' tags and keys as arguments
* '''find_in''': name of an array or container variable; if present, the location will not match unless it is also found stored in the variable
* '''radius''': matches if any location within the radius matches this filter ([http://www.wesnoth.org/wiki/StandardLocationFilter#Notes_about_Radius_Usage notes])
* '''[filter_radius]''': a standard location filter; normally the radius extends outwards from matching locations one step at a time without checking any additional information-- however, if this tag is present, the radius will be restricted so that it can only expand outwards in the directions where it passes the given location filter
* '''[and]''': an extra location filter. Unless a location matches the [and] filter, then it will be excluded. ''Note: [and],[or],and [not] extra location filters are considered after everything else in the containing filter (except radius, which is considered last in 1.3.8 and greater); they are then processed in the order encountered.''
* '''[or]''': an extra location filter. If a location matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.
* '''[not]''': an extra location filter. If a location matches the [not] filter, then that location will be excluded.
* '''[filter_adjacent_location]''': a standard location filter; if present the correct number of adjacent locations must match this filter
** '''count''': a number, range, or comma separated range; default "1-6"
** '''adjacent''': a comma separated list of directions; default "n,ne,se,s,sw,nw"

==Notes about Coordinate Usage==
When specifying coordinates, the following keys are used:
* '''x''': the first coordinate
* '''y''': the second coordinate

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

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

Commas(''',''') are used to separate coordinates into a list.
The '''x''' and '''y''' lists are then paired up, with each pair representing one hex or range.

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

==Notes about Radius Usage==
:If you aren't storing any locations successfully, it may be because you put the radius or filters in the wrong place for them to combine correctly.
[have_location]
terrain=Gg^Vh
[and]
x=$x1
y=$y1
radius=1
[/and]
[/have_location]
Note that the use of [and] here causes the radius to have a very different meaning. Normally, all of the criteria besides radius are checked, producing a set of hexes to which the radius is applied. This means, for example, that if you're trying to find "a hex without a unit on it within 5 hexes of (15, 23)", the code:
[have_location]
x,y=15,23
radius=5
[not]
[filter]
[/filter]
[/not]
[have_location]
will not work! First, it looks for a hex with x=15, y=23 without a unit on it. Then, it returns that hex and all hexes within 5 of it. If (15, 23) happens to be occupied, then it will return no hexes, because "all hexes within 5 hexes of (no hexes)" is still "no hexes". Instead, put an [and] around the x,y and radius requirements, and it will separately find "(15, 23) and all hexes within 5 of it" and "each of those hexes that doesn't have a unit on it", producing the desired result.
[[Category: WML Reference]]

StandardLocationFilter

2012-02-14T22:20:24Z

Anonymissimus:

{{WML Tags}}

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

The following attributes and sub-tags are permitted:

* '''time_of_day''': filter matches only on a given time of day (one of lawful, chaotic, neutral or liminal). Note: ''chaotic'', ''lawful'', ''neutral'' and ''liminal''; these are not times of day, these are ''alignments''. To match against 'dawn', 'dusk', 'first watch' etc., use the '''time_of_day_id''' key described below.
* '''time_of_day_id''': this accepts a list of one or more actual times of day, separated by commas. These IDs are taken from '''data/core/macros/schedules.cfg'''. Permissible values are case-sensitive: dawn, morning, afternoon, dusk, first_watch, second_watch, indoors, underground and deep_underground.
* '''terrain''': comma separated list of terrains. (See also: [http://www.wesnoth.org/wiki/FilterWML#Filtering_Terrains Filtering Terrains]).
* '''x,y''': the same as in the unit filter; supports any range ([http://www.wesnoth.org/wiki/StandardLocationFilter#Notes_about_Coordinate_Usage notes])
* '''[filter]''' with a [[StandardUnitFilter]] as argument; if present a unit must also be there
* '''owner_side''': If a valid side number, restricts stored locations to villages belonging to this side. If 0, restricts to all unowned locations (the whole map except villages which belong to some valid side). A hex is considered a village if its [ [[TerrainWML|terrain_type]] ]gives_income= parameter was set to yes.
*'''[filter_side]''': {{DevFeature1.11}}: If present, inline owner_side= is ignored. Restricts stored locations to villages, each of which must belong to any of the matching sides. If no sides match, restricts to unowned villages (and only these).
**'''[[StandardSideFilter]]''' tags and keys as arguments
* '''find_in''': name of an array or container variable; if present, the location will not match unless it is also found stored in the variable
* '''radius''': matches if any location within the radius matches this filter ([http://www.wesnoth.org/wiki/StandardLocationFilter#Notes_about_Radius_Usage notes])
* '''[filter_radius]''': a standard location filter; normally the radius extends outwards from matching locations one step at a time without checking any additional information-- however, if this tag is present, the radius will be restricted so that it can only expand outwards in the directions where it passes the given location filter
* '''[and]''': an extra location filter. Unless a location matches the [and] filter, then it will be excluded. ''Note: [and],[or],and [not] extra location filters are considered after everything else in the containing filter (except radius, which is considered last in 1.3.8 and greater); they are then processed in the order encountered.''
* '''[or]''': an extra location filter. If a location matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.
* '''[not]''': an extra location filter. If a location matches the [not] filter, then that location will be excluded.
* '''[filter_adjacent_location]''': a standard location filter; if present the correct number of adjacent locations must match this filter
** '''count''': a number, range, or comma separated range; default "1-6"
** '''adjacent''': a comma separated list of directions; default "n,ne,se,s,sw,nw"

==Notes about Coordinate Usage==
When specifying coordinates, the following keys are used:
* '''x''': the first coordinate
* '''y''': the second coordinate

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

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

Commas(''',''') are used to separate coordinates into a list.
The '''x''' and '''y''' lists are then paired up, with each pair representing one hex or range.

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

==Notes about Radius Usage==
:If you aren't storing any locations successfully, it may be because you put the radius or filters in the wrong place for them to combine correctly.
[have_location]
terrain=Gg^Vh
[and]
x=$x1
y=$y1
radius=1
[/and]
[/have_location]
Note that the use of [and] here causes the radius to have a very different meaning. Normally, all of the criteria besides radius are checked, producing a set of hexes to which the radius is applied. This means, for example, that if you're trying to find "a hex without a unit on it within 5 hexes of (15, 23)", the code:
[have_location]
x,y=15,23
radius=5
[not]
[filter]
[/filter]
[/not]
[have_location]
will not work! First, it looks for a hex with x=15, y=23 without a unit on it. Then, it returns that hex and all hexes within 5 of it. If (15, 23) happens to be occupied, then it will return no hexes, because "all hexes within 5 hexes of (no hexes)" is still "no hexes". Instead, put an [and] around the x,y and radius requirements, and it will separately find "(15, 23) and all hexes within 5 of it" and "each of those hexes that doesn't have a unit on it", producing the desired result.
[[Category: WML Reference]]

StandardLocationFilter

2012-02-14T22:03:31Z

Anonymissimus:

{{WML Tags}}

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

The following attributes and sub-tags are permitted:

* '''time_of_day''': filter matches only on a given time of day (one of lawful, chaotic, neutral or liminal). Note: ''chaotic'', ''lawful'', ''neutral'' and ''liminal''; these are not times of day, these are ''alignments''. To match against 'dawn', 'dusk', 'first watch' etc., use the '''time_of_day_id''' key described below.
* '''time_of_day_id''': this accepts a list of one or more actual times of day, separated by commas. These IDs are taken from '''data/core/macros/schedules.cfg'''. Permissible values are case-sensitive: dawn, morning, afternoon, dusk, first_watch, second_watch, indoors, underground and deep_underground.
* '''terrain''': comma separated list of terrains. (See also: [http://www.wesnoth.org/wiki/FilterWML#Filtering_Terrains Filtering Terrains]).
* '''x,y''': the same as in the unit filter; supports any range ([http://www.wesnoth.org/wiki/StandardLocationFilter#Notes_about_Coordinate_Usage notes])
* '''[filter]''' with a [[StandardUnitFilter]] as argument; if present a unit must also be there
* '''owner_side''': If a valid side number, restricts stored locations to villages belonging to this side. If 0, restricts to all unowned locations (the whole map except villages which belong to some side).
*'''[filter_side]''': {{DevFeature1.11}}: If present, inline owner_side= is ignored. Restricts stored locations to villages, each of which must belong to any of the matching sides. If no sides match, restricts to unowned villages (and only these).
**'''[[StandardSideFilter]]''' tags and keys as arguments
* '''find_in''': name of an array or container variable; if present, the location will not match unless it is also found stored in the variable
* '''radius''': matches if any location within the radius matches this filter ([http://www.wesnoth.org/wiki/StandardLocationFilter#Notes_about_Radius_Usage notes])
* '''[filter_radius]''': a standard location filter; normally the radius extends outwards from matching locations one step at a time without checking any additional information-- however, if this tag is present, the radius will be restricted so that it can only expand outwards in the directions where it passes the given location filter
* '''[and]''': an extra location filter. Unless a location matches the [and] filter, then it will be excluded. ''Note: [and],[or],and [not] extra location filters are considered after everything else in the containing filter (except radius, which is considered last in 1.3.8 and greater); they are then processed in the order encountered.''
* '''[or]''': an extra location filter. If a location matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.
* '''[not]''': an extra location filter. If a location matches the [not] filter, then that location will be excluded.
* '''[filter_adjacent_location]''': a standard location filter; if present the correct number of adjacent locations must match this filter
** '''count''': a number, range, or comma separated range; default "1-6"
** '''adjacent''': a comma separated list of directions; default "n,ne,se,s,sw,nw"

==Notes about Coordinate Usage==
When specifying coordinates, the following keys are used:
* '''x''': the first coordinate
* '''y''': the second coordinate

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

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

Commas(''',''') are used to separate coordinates into a list.
The '''x''' and '''y''' lists are then paired up, with each pair representing one hex or range.

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

==Notes about Radius Usage==
:If you aren't storing any locations successfully, it may be because you put the radius or filters in the wrong place for them to combine correctly.
[have_location]
terrain=Gg^Vh
[and]
x=$x1
y=$y1
radius=1
[/and]
[/have_location]
Note that the use of [and] here causes the radius to have a very different meaning. Normally, all of the criteria besides radius are checked, producing a set of hexes to which the radius is applied. This means, for example, that if you're trying to find "a hex without a unit on it within 5 hexes of (15, 23)", the code:
[have_location]
x,y=15,23
radius=5
[not]
[filter]
[/filter]
[/not]
[have_location]
will not work! First, it looks for a hex with x=15, y=23 without a unit on it. Then, it returns that hex and all hexes within 5 of it. If (15, 23) happens to be occupied, then it will return no hexes, because "all hexes within 5 hexes of (no hexes)" is still "no hexes". Instead, put an [and] around the x,y and radius requirements, and it will separately find "(15, 23) and all hexes within 5 of it" and "each of those hexes that doesn't have a unit on it", producing the desired result.
[[Category: WML Reference]]

DirectActionsWML

2012-02-14T21:49:34Z

Anonymissimus: /* [modify_ai] */

{{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; 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.
* '''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''': {{DevFeature1.11}} 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]].

=== [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. The unit is recalled free of charge, and is placed near the leader.
* [[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.
* '''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.

=== [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]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [gold][filter_side] is deprecated, use the new inline 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]]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.
* '''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
* '''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.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.

=== [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]] {{DevFeature1.11}} 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.
* '''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]] {{DevFeature1.11}} 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]] {{DevFeature1.11}} 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.
* '''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''': {{DevFeature1.11}} 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]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''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.
* '''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

=== [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 passable location is chosen. All target locations passed (see below) need to be passable hexes for the particular moved units.
* '''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.)

=== [modify_ai] ===
* [[StandardSideFilter]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [modify_ai][filter_side] is deprecated, use the new inline SSF.
Changes the AI for a specified side. See [[Customizing_AI_in_Wesnoth_1.8#.5Bmodify_ai.5D_tag]]

=== [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. Can add traits with immediate effect. 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]
type=Troll Rocklobber
[/filter]
hitpoints=10
[modifications]
[trait]
# first trait is unmodified
[/trait]
{TRAIT_HEALTHY}# second trait is replaced with the healthy trait
[/modifications]
[/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 hitpoints, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned.
* [[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 and removes all items on the tile the unit is on.
* '''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 level. In a campaign objects with the same id can be assigned once per level.
* '''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 'level', 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).
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
* '''[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 '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''silent''': whether or not messages should be suppressed. Default is "no".
* '''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.
* If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
* The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.

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

=== [allow_undo] ===
Allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move 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 move the first time.

=== [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 an 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.
* '''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.
* '''[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 an harmer, experience will be attributed like in regular combat.

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

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

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.

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

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

DirectActionsWML

2012-02-14T21:49:07Z

Anonymissimus: /* [modify_ai] */

{{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; 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.
* '''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''': {{DevFeature1.11}} 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]].

=== [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. The unit is recalled free of charge, and is placed near the leader.
* [[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.
* '''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.

=== [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]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [gold][filter_side] is deprecated, use the new inline 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]]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.
* '''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
* '''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.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.

=== [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]] {{DevFeature1.11}} 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.
* '''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]] {{DevFeature1.11}} 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]] {{DevFeature1.11}} 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.
* '''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''': {{DevFeature1.11}} 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]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''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.
* '''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

=== [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 passable location is chosen. All target locations passed (see below) need to be passable hexes for the particular moved units.
* '''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.)

=== [modify_ai] ===
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [modify_ai][filter_side] is deprecated, use the new inline SSF.
Changes the AI for a specified side. See [[Customizing_AI_in_Wesnoth_1.8#.5Bmodify_ai.5D_tag]]

=== [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. Can add traits with immediate effect. 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]
type=Troll Rocklobber
[/filter]
hitpoints=10
[modifications]
[trait]
# first trait is unmodified
[/trait]
{TRAIT_HEALTHY}# second trait is replaced with the healthy trait
[/modifications]
[/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 hitpoints, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned.
* [[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 and removes all items on the tile the unit is on.
* '''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 level. In a campaign objects with the same id can be assigned once per level.
* '''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 'level', 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).
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
* '''[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 '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''silent''': whether or not messages should be suppressed. Default is "no".
* '''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.
* If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
* The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.

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

=== [allow_undo] ===
Allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move 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 move the first time.

=== [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 an 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.
* '''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.
* '''[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 an harmer, experience will be attributed like in regular combat.

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

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

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.

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

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

DirectActionsWML

2012-02-14T21:45:24Z

Anonymissimus: /* [gold] */

{{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; 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.
* '''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''': {{DevFeature1.11}} 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]].

=== [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. The unit is recalled free of charge, and is placed near the leader.
* [[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.
* '''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.

=== [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]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [gold][filter_side] is deprecated, use the new inline 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]]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.
* '''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
* '''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.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.

=== [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]] {{DevFeature1.11}} 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.
* '''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]] {{DevFeature1.11}} 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]] {{DevFeature1.11}} 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.
* '''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''': {{DevFeature1.11}} 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]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''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.
* '''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

=== [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 passable location is chosen. All target locations passed (see below) need to be passable hexes for the particular moved units.
* '''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.)

=== [modify_ai] ===
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
Changes the AI for a specified side. See [[Customizing_AI_in_Wesnoth_1.8#.5Bmodify_ai.5D_tag]]

=== [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. Can add traits with immediate effect. 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]
type=Troll Rocklobber
[/filter]
hitpoints=10
[modifications]
[trait]
# first trait is unmodified
[/trait]
{TRAIT_HEALTHY}# second trait is replaced with the healthy trait
[/modifications]
[/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 hitpoints, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned.
* [[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 and removes all items on the tile the unit is on.
* '''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 level. In a campaign objects with the same id can be assigned once per level.
* '''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 'level', 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).
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
* '''[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 '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''silent''': whether or not messages should be suppressed. Default is "no".
* '''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.
* If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
* The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.

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

=== [allow_undo] ===
Allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move 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 move the first time.

=== [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 an 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.
* '''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.
* '''[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 an harmer, experience will be attributed like in regular combat.

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

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

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.

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

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

DirectActionsWML

2012-02-14T21:44:05Z

Anonymissimus: /* [gold] */

{{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; 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.
* '''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''': {{DevFeature1.11}} 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]].

=== [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. The unit is recalled free of charge, and is placed near the leader.
* [[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.
* '''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.

=== [gold] ===
Gives one side 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]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument {{DevFeature1.11}}: [gold][filter_side] is deprecated, use the new inline 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]]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.
* '''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
* '''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.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.

=== [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]] {{DevFeature1.11}} 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.
* '''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]] {{DevFeature1.11}} 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]] {{DevFeature1.11}} 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.
* '''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''': {{DevFeature1.11}} 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]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''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.
* '''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

=== [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 passable location is chosen. All target locations passed (see below) need to be passable hexes for the particular moved units.
* '''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.)

=== [modify_ai] ===
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
Changes the AI for a specified side. See [[Customizing_AI_in_Wesnoth_1.8#.5Bmodify_ai.5D_tag]]

=== [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. Can add traits with immediate effect. 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]
type=Troll Rocklobber
[/filter]
hitpoints=10
[modifications]
[trait]
# first trait is unmodified
[/trait]
{TRAIT_HEALTHY}# second trait is replaced with the healthy trait
[/modifications]
[/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 hitpoints, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned.
* [[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 and removes all items on the tile the unit is on.
* '''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 level. In a campaign objects with the same id can be assigned once per level.
* '''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 'level', 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).
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
* '''[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 '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''silent''': whether or not messages should be suppressed. Default is "no".
* '''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.
* If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
* The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.

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

=== [allow_undo] ===
Allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move 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 move the first time.

=== [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 an 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.
* '''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.
* '''[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 an harmer, experience will be attributed like in regular combat.

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

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

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.

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

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

DirectActionsWML

2012-02-14T21:40:51Z

Anonymissimus: /* [set_recruit] */

{{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; 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.
* '''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''': {{DevFeature1.11}} 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]].

=== [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. The unit is recalled free of charge, and is placed near the leader.
* [[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.
* '''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.

=== [gold] ===
Gives one side 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.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument

=== [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]]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.
* '''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
* '''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.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.

=== [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]] {{DevFeature1.11}} 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.
* '''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]] {{DevFeature1.11}} 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]] {{DevFeature1.11}} 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.
* '''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''': {{DevFeature1.11}} 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]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''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.
* '''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

=== [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 passable location is chosen. All target locations passed (see below) need to be passable hexes for the particular moved units.
* '''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.)

=== [modify_ai] ===
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
Changes the AI for a specified side. See [[Customizing_AI_in_Wesnoth_1.8#.5Bmodify_ai.5D_tag]]

=== [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. Can add traits with immediate effect. 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]
type=Troll Rocklobber
[/filter]
hitpoints=10
[modifications]
[trait]
# first trait is unmodified
[/trait]
{TRAIT_HEALTHY}# second trait is replaced with the healthy trait
[/modifications]
[/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 hitpoints, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned.
* [[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 and removes all items on the tile the unit is on.
* '''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 level. In a campaign objects with the same id can be assigned once per level.
* '''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 'level', 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).
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
* '''[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 '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''silent''': whether or not messages should be suppressed. Default is "no".
* '''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.
* If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
* The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.

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

=== [allow_undo] ===
Allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move 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 move the first time.

=== [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 an 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.
* '''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.
* '''[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 an harmer, experience will be attributed like in regular combat.

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

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

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.

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

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

DirectActionsWML

2012-02-14T21:40:02Z

Anonymissimus: /* [disallow_recruit] */

{{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; 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.
* '''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''': {{DevFeature1.11}} 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]].

=== [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. The unit is recalled free of charge, and is placed near the leader.
* [[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.
* '''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.

=== [gold] ===
Gives one side 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.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument

=== [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]]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.
* '''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
* '''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.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.

=== [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]] {{DevFeature1.11}} 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.
* '''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]] {{DevFeature1.11}} 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.

=== [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.
* '''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''': {{DevFeature1.11}} 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]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''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.
* '''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

=== [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 passable location is chosen. All target locations passed (see below) need to be passable hexes for the particular moved units.
* '''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.)

=== [modify_ai] ===
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
Changes the AI for a specified side. See [[Customizing_AI_in_Wesnoth_1.8#.5Bmodify_ai.5D_tag]]

=== [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. Can add traits with immediate effect. 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]
type=Troll Rocklobber
[/filter]
hitpoints=10
[modifications]
[trait]
# first trait is unmodified
[/trait]
{TRAIT_HEALTHY}# second trait is replaced with the healthy trait
[/modifications]
[/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 hitpoints, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned.
* [[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 and removes all items on the tile the unit is on.
* '''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 level. In a campaign objects with the same id can be assigned once per level.
* '''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 'level', 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).
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
* '''[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 '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''silent''': whether or not messages should be suppressed. Default is "no".
* '''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.
* If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
* The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.

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

=== [allow_undo] ===
Allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move 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 move the first time.

=== [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 an 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.
* '''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.
* '''[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 an harmer, experience will be attributed like in regular combat.

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

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

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.

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

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

DirectActionsWML

2012-02-14T21:39:32Z

Anonymissimus: /* [allow_recruit] */

{{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; 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.
* '''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''': {{DevFeature1.11}} 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]].

=== [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. The unit is recalled free of charge, and is placed near the leader.
* [[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.
* '''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.

=== [gold] ===
Gives one side 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.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument

=== [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]]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.
* '''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
* '''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.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.

=== [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]] {{DevFeature1.11}} 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.
* '''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.

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

=== [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.
* '''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''': {{DevFeature1.11}} 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]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''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.
* '''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

=== [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 passable location is chosen. All target locations passed (see below) need to be passable hexes for the particular moved units.
* '''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.)

=== [modify_ai] ===
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
Changes the AI for a specified side. See [[Customizing_AI_in_Wesnoth_1.8#.5Bmodify_ai.5D_tag]]

=== [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. Can add traits with immediate effect. 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]
type=Troll Rocklobber
[/filter]
hitpoints=10
[modifications]
[trait]
# first trait is unmodified
[/trait]
{TRAIT_HEALTHY}# second trait is replaced with the healthy trait
[/modifications]
[/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 hitpoints, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned.
* [[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 and removes all items on the tile the unit is on.
* '''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 level. In a campaign objects with the same id can be assigned once per level.
* '''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 'level', 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).
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
* '''[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 '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''silent''': whether or not messages should be suppressed. Default is "no".
* '''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.
* If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
* The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.

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

=== [allow_undo] ===
Allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move 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 move the first time.

=== [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 an 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.
* '''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.
* '''[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 an harmer, experience will be attributed like in regular combat.

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

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

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.

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

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

StandardLocationFilter

2012-02-10T19:38:36Z

Anonymissimus: document owner_side again better/correctly...

{{WML Tags}}

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

The following attributes and sub-tags are permitted:

* '''time_of_day''': filter matches only on a given time of day (one of lawful, chaotic, neutral or liminal). Note: ''chaotic'', ''lawful'', ''neutral'' and ''liminal''; these are not times of day, these are ''alignments''. To match against 'dawn', 'dusk', 'first watch' etc., use the '''time_of_day_id''' key described below.
* '''time_of_day_id''': this accepts a list of one or more actual times of day, separated by commas. These IDs are taken from '''data/core/macros/schedules.cfg'''. Permissible values are case-sensitive: dawn, morning, afternoon, dusk, first_watch, second_watch, indoors, underground and deep_underground.
* '''terrain''': comma separated list of terrains. (See also: [http://www.wesnoth.org/wiki/FilterWML#Filtering_Terrains Filtering Terrains]).
* '''x,y''': the same as in the unit filter; supports any range ([http://www.wesnoth.org/wiki/StandardLocationFilter#Notes_about_Coordinate_Usage notes])
* '''[filter]''' with a [[StandardUnitFilter]] as argument; if present a unit must also be there
* '''owner_side''': If a valid side number, restricts stored locations to villages belonging to this side. If 0, restricts to all unowned locations (the whole map except villages which belong to some side).
* '''find_in''': name of an array or container variable; if present, the location will not match unless it is also found stored in the variable
* '''radius''': matches if any location within the radius matches this filter ([http://www.wesnoth.org/wiki/StandardLocationFilter#Notes_about_Radius_Usage notes])
* '''[filter_radius]''': a standard location filter; normally the radius extends outwards from matching locations one step at a time without checking any additional information-- however, if this tag is present, the radius will be restricted so that it can only expand outwards in the directions where it passes the given location filter
* '''[and]''': an extra location filter. Unless a location matches the [and] filter, then it will be excluded. ''Note: [and],[or],and [not] extra location filters are considered after everything else in the containing filter (except radius, which is considered last in 1.3.8 and greater); they are then processed in the order encountered.''
* '''[or]''': an extra location filter. If a location matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.
* '''[not]''': an extra location filter. If a location matches the [not] filter, then that location will be excluded.
* '''[filter_adjacent_location]''': a standard location filter; if present the correct number of adjacent locations must match this filter
** '''count''': a number, range, or comma separated range; default "1-6"
** '''adjacent''': a comma separated list of directions; default "n,ne,se,s,sw,nw"

==Notes about Coordinate Usage==
When specifying coordinates, the following keys are used:
* '''x''': the first coordinate
* '''y''': the second coordinate

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

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

Commas(''',''') are used to separate coordinates into a list.
The '''x''' and '''y''' lists are then paired up, with each pair representing one hex or range.

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

==Notes about Radius Usage==
:If you aren't storing any locations successfully, it may be because you put the radius or filters in the wrong place for them to combine correctly.
[have_location]
terrain=Gg^Vh
[and]
x=$x1
y=$y1
radius=1
[/and]
[/have_location]
Note that the use of [and] here causes the radius to have a very different meaning. Normally, all of the criteria besides radius are checked, producing a set of hexes to which the radius is applied. This means, for example, that if you're trying to find "a hex without a unit on it within 5 hexes of (15, 23)", the code:
[have_location]
x,y=15,23
radius=5
[not]
[filter]
[/filter]
[/not]
[have_location]
will not work! First, it looks for a hex with x=15, y=23 without a unit on it. Then, it returns that hex and all hexes within 5 of it. If (15, 23) happens to be occupied, then it will return no hexes, because "all hexes within 5 hexes of (no hexes)" is still "no hexes". Instead, put an [and] around the x,y and radius requirements, and it will separately find "(15, 23) and all hexes within 5 of it" and "each of those hexes that doesn't have a unit on it", producing the desired result.
[[Category: WML Reference]]

InternalActionsWML

2012-02-09T21:45:34Z

Anonymissimus: /* [store_villages] */ simplify/improve documentation for store_villages

{{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 dollars 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. '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. See [[BuildingMultiplayerExamples]] for more info on the MP case.

* '''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 comma) of the referenced variable.

* '''fpart''': Assigns the decimal part (the part to the right of the comma) 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

=== 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. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden', 'user_team_name', 'color', 'controller', 'village_gold', 'recruit', and 'side' (the $side_number of the side belonging to this container).

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

''note: In networked multiplayer, the controller attribute is ambiguous. Be very careful or you have OOS errors.''

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

* '''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_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 [[InternalActionsWMLUnitTags|here]]. 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).

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

==== [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: The only advantage/difference this tag has, in comparison to using [store_locations]terrain=*^V*, is that the amount of hexes which are considered for a possible match is previously restricted to those with villages.

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

==== [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]
length = 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.
hexes = in 1.11, this will replace the length key above
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]
To read the total length of the path on 1.10, use ''path.step.length''. 
{{DevFeature1.11}} ''length'' is replaced by ''hexes'' in the output array.

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

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

* '''name''': the name of event to trigger

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

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

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

StandardLocationFilter

2012-02-09T21:35:50Z

Anonymissimus: make owner_side documentation more precise

{{WML Tags}}

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

The following attributes and sub-tags are permitted:

* '''time_of_day''': filter matches only on a given time of day (one of lawful, chaotic, neutral or liminal). Note: ''chaotic'', ''lawful'', ''neutral'' and ''liminal''; these are not times of day, these are ''alignments''. To match against 'dawn', 'dusk', 'first watch' etc., use the '''time_of_day_id''' key described below.
* '''time_of_day_id''': this accepts a list of one or more actual times of day, separated by commas. These IDs are taken from '''data/core/macros/schedules.cfg'''. Permissible values are case-sensitive: dawn, morning, afternoon, dusk, first_watch, second_watch, indoors, underground and deep_underground.
* '''terrain''': comma separated list of terrains. (See also: [http://www.wesnoth.org/wiki/FilterWML#Filtering_Terrains Filtering Terrains]).
* '''x,y''': the same as in the unit filter; supports any range ([http://www.wesnoth.org/wiki/StandardLocationFilter#Notes_about_Coordinate_Usage notes])
* '''[filter]''' with a [[StandardUnitFilter]] as argument; if present a unit must also be there
* '''owner_side''': If given, restricts stored locations to villages, and these to the given side number (0 for unowned villages).
* '''find_in''': name of an array or container variable; if present, the location will not match unless it is also found stored in the variable
* '''radius''': matches if any location within the radius matches this filter ([http://www.wesnoth.org/wiki/StandardLocationFilter#Notes_about_Radius_Usage notes])
* '''[filter_radius]''': a standard location filter; normally the radius extends outwards from matching locations one step at a time without checking any additional information-- however, if this tag is present, the radius will be restricted so that it can only expand outwards in the directions where it passes the given location filter
* '''[and]''': an extra location filter. Unless a location matches the [and] filter, then it will be excluded. ''Note: [and],[or],and [not] extra location filters are considered after everything else in the containing filter (except radius, which is considered last in 1.3.8 and greater); they are then processed in the order encountered.''
* '''[or]''': an extra location filter. If a location matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.
* '''[not]''': an extra location filter. If a location matches the [not] filter, then that location will be excluded.
* '''[filter_adjacent_location]''': a standard location filter; if present the correct number of adjacent locations must match this filter
** '''count''': a number, range, or comma separated range; default "1-6"
** '''adjacent''': a comma separated list of directions; default "n,ne,se,s,sw,nw"

==Notes about Coordinate Usage==
When specifying coordinates, the following keys are used:
* '''x''': the first coordinate
* '''y''': the second coordinate

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

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

Commas(''',''') are used to separate coordinates into a list.
The '''x''' and '''y''' lists are then paired up, with each pair representing one hex or range.

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

==Notes about Radius Usage==
:If you aren't storing any locations successfully, it may be because you put the radius or filters in the wrong place for them to combine correctly.
[have_location]
terrain=Gg^Vh
[and]
x=$x1
y=$y1
radius=1
[/and]
[/have_location]
Note that the use of [and] here causes the radius to have a very different meaning. Normally, all of the criteria besides radius are checked, producing a set of hexes to which the radius is applied. This means, for example, that if you're trying to find "a hex without a unit on it within 5 hexes of (15, 23)", the code:
[have_location]
x,y=15,23
radius=5
[not]
[filter]
[/filter]
[/not]
[have_location]
will not work! First, it looks for a hex with x=15, y=23 without a unit on it. Then, it returns that hex and all hexes within 5 of it. If (15, 23) happens to be occupied, then it will return no hexes, because "all hexes within 5 hexes of (no hexes)" is still "no hexes". Instead, put an [and] around the x,y and radius requirements, and it will separately find "(15, 23) and all hexes within 5 of it" and "each of those hexes that doesn't have a unit on it", producing the desired result.
[[Category: WML Reference]]

InternalActionsWML

2012-02-09T21:27:48Z

Anonymissimus: /* [store_locations] */ correct store_locations documentation

{{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 dollars 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. '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. See [[BuildingMultiplayerExamples]] for more info on the MP case.

* '''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 comma) of the referenced variable.

* '''fpart''': Assigns the decimal part (the part to the right of the comma) 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

=== 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. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden', 'user_team_name', 'color', 'controller', 'village_gold', 'recruit', and 'side' (the $side_number of the side belonging to this container).

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

''note: In networked multiplayer, the controller attribute is ambiguous. Be very careful or you have OOS errors.''

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

* '''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_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 [[InternalActionsWMLUnitTags|here]]. 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).

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

==== [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'. Although only owner_side and terrain filters are explained below, all features of the [[StandardLocationFilter]] are fully supported.

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

* '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages.

* '''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_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

==== [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]
length = 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.
hexes = in 1.11, this will replace the length key above
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]
To read the total length of the path on 1.10, use ''path.step.length''. 
{{DevFeature1.11}} ''length'' is replaced by ''hexes'' in the output array.

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

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

* '''name''': the name of event to trigger

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

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

== 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/Events

2012-02-08T22:10:03Z

Anonymissimus: /* wesnoth.register_wml_action */

This page describes the [[LuaWML]] functions and helpers for interacting with events and action handlers.

==== wesnoth.fire ====

Fires a [[ActionWML|WML action]]. Argument 1 is the name of the action. Argument 2 is the WML table describing the action. Note: WML variables are substituted.

wesnoth.fire("message", { speaker="narrator", message=_ "Hello World!" })

==== wesnoth.register_wml_action ====
{{DevFeature1.11}}: This function is deprecated; directly write into [[#wesnoth.wml_actions]] instead.

Registers the second argument as a handler for the given action tag. When the game encounters this tag when executing [[ActionWML]] (for example in an event), it fires the action handler and passes the content of the WML object as the first argument. Thus, this function creates new types of [[ActionWML]].

If the registered function raises an error with a message starting with ''~wml:'', it will not be displayed as a Lua error with a backtrace but as a standard WML error. (See also [[#helper.wml_error]].) The following script defines a [freeze_unit] tag that sets to 0 the move points of the unit with the given id.

wesnoth.register_wml_action("freeze_unit",
function(cfg)
local unit_id = cfg.id or error("~wml:[freeze_unit] expects an id= attribute.", 0)
helper.modify_unit({ id = unit_id }, { moves = 0 })
end
)

# The new tag can now be used in plain WML code.
[freeze_unit]
id=Delfador
[/freeze_unit]

The function returns the previous action handler. Its metatable appears as '''"wml action handler"'''. This handler can be called to delegate part of the action, if needed. For instance, the following script modifies the [[InterfaceActionsWML#Other interface tags|[print]]] tag so that messages are displayed with a bigger font.

local old_print_handler
old_print_handler = wesnoth.register_wml_action("print",
function(cfg)
-- Do not perform variable substitution.
local new_cfg = cfg.__literal
-- Modify the size field and call the previous handler.
new_cfg.size = (cfg.size or 12) + 10
old_print_handler(cfg)
end
)

Note that the data coming from the WML tag are stored in a read-only object and variable substitution happens on the fly when accessing attributes and children. The metatable of this proxy object appears as '''"wml object"'''. See [[LuaWML#Encoding WML objects into Lua tables]] for more details.

If the name of a tag starts as ''filter'', it is ignored when the actions of an event are executed. These names are indeed reserved for event filtering, e.g. [filter], [filter_weapon], and so on. It is therefore useless to define action tags with such names.

==== wesnoth.wml_actions ====

This is not a function but an associative table indexed by WML action names. It contains functions performing the corresponding actions. Using these functions is similar to calling [[#wesnoth.fire]], while setting entries of the table is similar to calling [[#wesnoth.register_wml_action]].

function wesnoth.wml_actions.freeze_unit(cfg)
local unit_id = cfg.id or helper.wml_error "[freeze_unit] expects an id= attribute."
helper.modify_unit({ id = unit_id }, { moves = 0 })
end

Note: When calling an action handler directly through its function stored in ''wesnoth.wml_actions'', the engine is not involved. As a consequence, whether variable substitution will happen is up to the handler. In particular, if the argument is a plain table, the caller should have substituted WML variables beforehand to be on the safe side. Moreover, table arguments might be modified by the action handler, so they should usually not be reused for consecutive calls. If variable substitution should happen and/or table content should be preserved, one can call [[#wesnoth.tovconfig]] and pass its result to the handler. Calling [[#wesnoth.fire]] is another possibility.

==== wesnoth.game_events ====

This is not a function but an associative table indexed by engine action names. It contains function hooks the engine calls whenever it performs a particular action.

* '''on_save''': function called when the engine (auto)saves a scenario file; it should return a WML table and the children of this table are added to the savefile.
* '''on_load''': function called when the engine loads a scenario file; its argument is a WML table that contains all the children of the savefile that the engine did not handle.
* '''on_event''': function called before each WML event is executed; its argument is the event name; other event arguments can be recovered from [[LuaWML:Misc#wesnoth.current|wesnoth.current.event_context]].

The ''on_save'' and ''on_load'' hooks can be used to manipulate data that are neither meant to be forwarded to the next level nor substituted on the fly. (For either of these two purposes, WML variables are the best choice.) For instance, toplevel tags like [item], [event], [time_area], and so on, could typically be handled by such hooks.

-- some value that survives save/load cycles, but that is not forwarded to the next level
local level_local_data = 0

local old_on_load = wesnoth.game_event.on_load
function wesnoth.game_event.on_load(cfg)
for i = 1,#cfg do
if cfg[i][1] == "my_data" then
-- recover the value stored in the savefile
level_local_data = cfg[i][2].value
-- erase the child, since it has been handled
table.remove(cfg, i)
break
end
end
-- call the previous hook, in case there are still some containers in the savefile
old_on_load(cfg)
end

local old_on_save = wesnoth.game_events.on_save
function wesnoth.game_events.on_save()
-- call the previous hook, in case it had some containers to store
local cfg = old_on_save()
-- add our own container to them
table.insert(cfg, { "my_data", { value = level_local_data } })
-- tell the engine to store them in the savefile
return cfg
end

Note: since the ''on_load'' hook is called very early in the scenario, it cannot be set inside a [lua] tag in an [event], not even a ''preload'' one. It has to be set inside a [lua] tag outside or at [scenario] level.

Note: Some tag names are reserved for engine use and should not be modified using the above on_save/on_load method. These tag names are:
"color_palette", "color_range", "era", "event", "generator",
"label", "lua", "menu_item", "music", "side", "sound_source", "story",
"terrain_graphics", "time", "time_area", "tunnel", "variables"

==== wesnoth.fire_event ====

Fires all the WML events with the given name. Optional parameters allow passing two locations and two tables. These parameters will be matched against the [filter], [filter_second], [filter_attack], and [filter_second_attack] of any event handler, and are used to fill the WML variables "unit", "second_unit", "weapon", and "second_weapon". These parameters can also be read through ''current.event_context''. The function returns a boolean indicating whether the game state was modified.

wesnoth.fire_event("explosion", 17, 42, { damage = "fire" })

==== wesnoth.eval_conditional ====

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

local result = wesnoth.eval_conditional {
{ "have_unit", { id = "hero" } },
{ "variable", { name = "counter", numerical_equals = "$old_counter" } }
}

==== wesnoth.tovconfig ====

Converts a WML table into a proxy object which performs variable substitution on the fly.

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

==== helper.set_wml_action_metatable ====

Sets the metable of a table so that it can be used to fire WML actions. Returns the table. The fields of the table are then simple wrappers around a call to [[#wesnoth.fire]].

local W = helper.set_wml_action_metatable {}
W.message { speaker = "narrator", message = "?" }

==== helper.wml_error ====

Interrupts the current execution and displays a chat message that looks like a WML error.

local names = cfg.name or helper.wml_error("[clear_variable] missing required name= attribute.")

==== helper.literal ====

Returns the ''__literal'' field of its argument if it is a userdata, the argument itself otherwise. This function is meant to be called when a WML action handler can be called indifferently from WML (hence receiving a userdata) or from Lua (hence possibly receiving a table).

function wml_actions.display_literal_value(cfg)
cfg = helper.literal(cfg)
wesnoth.message(tostring(cfg.value))
end

Note: when the argument is a plain table, the function returns it as is. In particular, modifying the fields of the returned table causes the original table to be modified too.

==== helper.parsed ====

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

==== helper.shallow_literal ====

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

==== helper.shallow_parsed ====

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

[[Category: Lua Reference]]

LuaWML/Units

2012-02-08T22:01:48Z

Anonymissimus: /* wesnoth.unit_types */

This page describes the [[LuaWML]] functions for handling units.

A unit is a proxy table with the following fields:
* '''x''', '''y''': integers (read only, read/write if the unit is not on the map)
* '''side''': integer (read/write)
* '''id''': string (read only)
* '''type''': string (read only)
* '''name''': translatable string (read only)
* '''hitpoints''', '''max_hitpoints''', '''experience''', '''max_experience''', '''max_moves''': integers (read only)
* '''max_attacks''': integer (read only)
* '''attacks_left''': integer (read/write) Setting below 0 is limited to 0.
* '''extra_recruit''': table (read/write)
* '''advances_to''': table (read/write)
* '''hitpoints''', '''experience''': integer (read/write)
* '''moves''': integer (read/write)
* '''resting''': boolean (read/write)
* '''hidden''': boolean (read/write)
* '''petrified''', '''canrecruit''': booleans (read only)
* '''role''', '''facing''': strings (read/write)
* '''status''': proxy associative table (read only, read/write fields)
* '''image_mods''': string (read only)
* '''variables''': proxy associative table (read only, read/write fields, including ''variables.__cfg''), only toplevel named fields are proxied
* '''valid''': string or nil (read only)
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"unit"'''.

A unit can be either visible on the map ([[#wesnoth.get_units]], [[#wesnoth.put_unit]]), or on a recall list ([[#wesnoth.get_recall_units]], [[#wesnoth.put_recall_unit]]), or private to the Lua code ([[#wesnoth.create_unit]], [[#wesnoth.copy_unit]], [[#wesnoth.extract_unit]]). The Lua code has complete control over the private units; they will not be modified unless accessed through the proxy unit. Units on the map and on the recall lists, however, can be modified by the user, the engine, WML, independently of the Lua code. In particular, if a unit is killed, any further use of the proxy unit will cause an error. For units on the map, the proxy unit is valid as long as there is a unit on the map that has the same "underlying_id" WML field as the original one. The behavior is similar for units on the recall lists. The ''valid'' field reflects the unit availability by returning '''"map"''', '''"recall"''', '''"private"''', or ''nil''. The latter value is used for units that were removed (e.g. killed). In that case, the ''valid'' field is the only one that can be read without causing an error.

The term "proxy", here in particular "proxy unit", means that the variable retrieved in the lua code (with get_units for example) is an accessor (reference) to the C++ object which represents that unit. This is very different from unit variables obtained by [store_unit] in wml. The fields marked as "writable" above can be modified without the need to use put_unit afterwards. This same reason explains that modifications to the unit from outside the lua code (like [kill] invalidating the proxy unit) have immediate effect on the lua code's proxy unit variable (with the exception of private proxy units).

==== wesnoth.get_units ====

Returns an array of all the units on the map matching the WML filter passed as the first argument. See [[StandardUnitFilter]] for details about filters.

local leaders_on_side_two = get_units { side = 2, canrecruit = true }
local name_of_leader = leaders_on_side_two[1].name

==== wesnoth.get_unit ====

Returns the unit at the given location or with the given underlying ID.

local args = ...
local unit = wesnoth.get_unit(args.x1, args.y1)

==== wesnoth.match_unit ====

Returns true if the given unit matches the WML filter passed as the second argument.

assert(unit.canrecruit == wesnoth.match_unit(unit, { canrecruit = true }))

==== wesnoth.put_unit ====

Places a unit on the map. This unit is described either by a WML table or by a proxy unit. Coordinates can be passed as the first two arguments, otherwise the table is expected to have two fields '''x''' and '''y''', which indicate where the unit will be placed. If the function is called with coordinates only, the unit on the map at the given coordinates is removed instead.

-- create a unit with random traits, then erase it
wesnoth.put_unit(17, 42, { type = "Elvish Lady" })
wesnoth.put_unit(17, 42)

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on a recall list, it no longer is; and if the unit was on the map, it has been moved to the new location. Note: passing a WML table is just a shortcut for calling [[#wesnoth.create_unit]] and then putting the resulting unit on the map.

-- move the leader back to the top-left corner
wesnoth.put_unit(1, 1, wesnoth.get_units({ canrecruit = true })[1])

==== wesnoth.get_recall_units ====

Returns an array of all the units on the recall lists matching the WML filter passed as the first argument.

==== wesnoth.put_recall_unit ====

Places a unit on a recall list. This unit is described either by a WML table or by a proxy unit. The side of the recall list is given by the second argument, or by the side of the unit if missing.

-- put the unit at location 17,42 on the recall list for side 2
wesnoth.put_recall_unit(wesnoth.get_units({ x= 17, y = 42 })[1], 2)

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on the map, it no longer is. Note: passing a WML table is just a shortcut for calling [[#wesnoth.create_unit]] and then putting the resulting unit on a recall list.

==== wesnoth.create_unit ====

Creates a private unit from a WML table.

local u = wesnoth.create_unit { type = "White Mage", gender = "female" }

==== wesnoth.copy_unit ====

Creates a private unit from another unit.

-- extract a unit from the map
local u = wesnoth.copy_unit(wesnoth.get_units({ type = "Thug" })[1])
wesnoth.put_unit(u.x, u.y)
-- u is still valid at this point

==== wesnoth.extract_unit ====

Removes a unit from the map or from a recall list and makes it private.

-- remove all the units from the recall list of side 1 and put them in a WML container
local l = {}
for i,u in ipairs(wesnoth.get_recall_units { side = 1 }) do
wesnoth.extract_unit(u)
table.insert(l, u.__cfg)
end
helper.set_variable_array("player_recall_list", l)

Note: if the unit is on the map, it is just a shortcut for calling [[#wesnoth.copy_unit]] and then [[#wesnoth.put_unit]] without a unit. It is, however, the only way for removing a unit from a recall list without putting it on the map.

==== wesnoth.add_modification ====

Modifies a given unit. It needs to be a proxy unit. The second argument is the type of the modification (either trait, object, or advance). The option "advance" applies effects as if the unit would advance (e.g. AMLA effects). The third argument is a WML table describing the effect, so mostly containing '''[effect]''' children. See [[EffectWML]] for details about effects.

local u = wesnoth.get_units { canrecruit = true }[1]
wesnoth.add_modification(u, "object", { { "effect", { apply_to = "image_mod", replace = "RC(red>blue)" } } })

==== wesnoth.unit_resistance ====

Returns the resistance of a unit against an attack type. (Note: it is a WML resistance. So the higher it is, the weaker the unit is.) The third argument indicates whether the unit is the attacker. Last arguments are the coordinates of an optional map location (for the purpose of taking abilities into account).

local fire_resistance = 100 - wesnoth.unit_resistance(u, "fire")

==== wesnoth.unit_defense ====

Returns the defense of a unit on a particular terrain. (Note: it is a WML defense. So the higher it is, the weaker the unit is.)

local flat_defense = 100 - wesnoth.unit_defense(u, "Gt")

==== wesnoth.unit_movement_cost ====

Returns the movement cost of a unit on a particular terrain.

local move_cost = wesnoth.unit_movement_cost(u, "Gt")

==== wesnoth.unit_ability ====

Returns true if the unit is currently under effect by an ability with this given TAG NAME. This means that the ability could be owned by the unit itself, or by an adjacent unit.

function has_teleport(u)
return wesnoth.unit_ability(u, "teleport")
end

==== wesnoth.get_unit_type_ids ====
{{DevFeature1.11}}: This function is deprecated, use wesnoth.unit_types.

==== wesnoth.get_unit_type ====
{{DevFeature1.11}}: This function is deprecated, use wesnoth.unit_types instead.

==== wesnoth.unit_types ====

This is not a function but a table indexed by unit type ids. Its elements are proxy tables with these fields:

* '''id''': string
* '''name''': translatable string (read only)
* '''max_moves''', '''max_experience''', '''max_hitpoints''', '''level''', '''cost''': integers (read only)
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"unit type"'''.

local lich_cost = wesnoth.unit_types["Ancient Lich"].cost

==== wesnoth.races ====

This is not a function but a table indexed by race ids. Its elements are proxy tables for all races the engine knows about.
known fields of each element:
* '''id''': string
* '''description''', '''name''', '''plural_name''' (translatable strings)
* '''num_traits''' (integer)
* '''ignore_global_traits''' (boolean)
* '''undead_variation''' (string)
(all read only)
* '''__cfg''': WML table (dump)

wesnoth.message(tostring(wesnoth.races["lizard"].name))

==== wesnoth.get_traits ====

Returns a table with named fields (trait id strings) holding the wml tables defining the traits. arguments: none. All global traits the engine knows about, race-specific traits are not included.
Known fields and subtags of each element are the ones which were given in the wml definition of the [[SingleUnitWML|trait]].
wesnoth.message(tostring(wesnoth.get_traits().strong.male_name))

==== wesnoth.simulate_combat ====

Computes the hitpoint distribution and status chance after a combat between two units. Optional integers can be passed to select a particular weapon, otherwise the "best" one is selected. The first unit is the attacker; it does not have to be on the map, though its location should be meaningful. The second unit is the defender; it has to be on the map.

When giving the attack, the parameter is the attack id (integer) and not an element from the table returned by helper.child_range(att, "attack").

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

==== wesnoth.transform_unit ====

Changes the type of a unit and adjust attributes accordingly. Note that hitpoints might be modified accordingly to the unit type.

local ev = wesnoth.current.event_context
local u = wesnoth.get_units{x=ev.x1, y=ev.y1}[1]
local old_hp = u.hitpoints
wesnoth.transform_unit(u, "Skeleton")
u.hitpoints = old_hp
u.status.poisoned = false

[[Category: Lua Reference]]

LuaWML/Units

2012-02-08T21:59:54Z

Anonymissimus: /* wesnoth.get_unit_type */

This page describes the [[LuaWML]] functions for handling units.

A unit is a proxy table with the following fields:
* '''x''', '''y''': integers (read only, read/write if the unit is not on the map)
* '''side''': integer (read/write)
* '''id''': string (read only)
* '''type''': string (read only)
* '''name''': translatable string (read only)
* '''hitpoints''', '''max_hitpoints''', '''experience''', '''max_experience''', '''max_moves''': integers (read only)
* '''max_attacks''': integer (read only)
* '''attacks_left''': integer (read/write) Setting below 0 is limited to 0.
* '''extra_recruit''': table (read/write)
* '''advances_to''': table (read/write)
* '''hitpoints''', '''experience''': integer (read/write)
* '''moves''': integer (read/write)
* '''resting''': boolean (read/write)
* '''hidden''': boolean (read/write)
* '''petrified''', '''canrecruit''': booleans (read only)
* '''role''', '''facing''': strings (read/write)
* '''status''': proxy associative table (read only, read/write fields)
* '''image_mods''': string (read only)
* '''variables''': proxy associative table (read only, read/write fields, including ''variables.__cfg''), only toplevel named fields are proxied
* '''valid''': string or nil (read only)
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"unit"'''.

A unit can be either visible on the map ([[#wesnoth.get_units]], [[#wesnoth.put_unit]]), or on a recall list ([[#wesnoth.get_recall_units]], [[#wesnoth.put_recall_unit]]), or private to the Lua code ([[#wesnoth.create_unit]], [[#wesnoth.copy_unit]], [[#wesnoth.extract_unit]]). The Lua code has complete control over the private units; they will not be modified unless accessed through the proxy unit. Units on the map and on the recall lists, however, can be modified by the user, the engine, WML, independently of the Lua code. In particular, if a unit is killed, any further use of the proxy unit will cause an error. For units on the map, the proxy unit is valid as long as there is a unit on the map that has the same "underlying_id" WML field as the original one. The behavior is similar for units on the recall lists. The ''valid'' field reflects the unit availability by returning '''"map"''', '''"recall"''', '''"private"''', or ''nil''. The latter value is used for units that were removed (e.g. killed). In that case, the ''valid'' field is the only one that can be read without causing an error.

The term "proxy", here in particular "proxy unit", means that the variable retrieved in the lua code (with get_units for example) is an accessor (reference) to the C++ object which represents that unit. This is very different from unit variables obtained by [store_unit] in wml. The fields marked as "writable" above can be modified without the need to use put_unit afterwards. This same reason explains that modifications to the unit from outside the lua code (like [kill] invalidating the proxy unit) have immediate effect on the lua code's proxy unit variable (with the exception of private proxy units).

==== wesnoth.get_units ====

Returns an array of all the units on the map matching the WML filter passed as the first argument. See [[StandardUnitFilter]] for details about filters.

local leaders_on_side_two = get_units { side = 2, canrecruit = true }
local name_of_leader = leaders_on_side_two[1].name

==== wesnoth.get_unit ====

Returns the unit at the given location or with the given underlying ID.

local args = ...
local unit = wesnoth.get_unit(args.x1, args.y1)

==== wesnoth.match_unit ====

Returns true if the given unit matches the WML filter passed as the second argument.

assert(unit.canrecruit == wesnoth.match_unit(unit, { canrecruit = true }))

==== wesnoth.put_unit ====

Places a unit on the map. This unit is described either by a WML table or by a proxy unit. Coordinates can be passed as the first two arguments, otherwise the table is expected to have two fields '''x''' and '''y''', which indicate where the unit will be placed. If the function is called with coordinates only, the unit on the map at the given coordinates is removed instead.

-- create a unit with random traits, then erase it
wesnoth.put_unit(17, 42, { type = "Elvish Lady" })
wesnoth.put_unit(17, 42)

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on a recall list, it no longer is; and if the unit was on the map, it has been moved to the new location. Note: passing a WML table is just a shortcut for calling [[#wesnoth.create_unit]] and then putting the resulting unit on the map.

-- move the leader back to the top-left corner
wesnoth.put_unit(1, 1, wesnoth.get_units({ canrecruit = true })[1])

==== wesnoth.get_recall_units ====

Returns an array of all the units on the recall lists matching the WML filter passed as the first argument.

==== wesnoth.put_recall_unit ====

Places a unit on a recall list. This unit is described either by a WML table or by a proxy unit. The side of the recall list is given by the second argument, or by the side of the unit if missing.

-- put the unit at location 17,42 on the recall list for side 2
wesnoth.put_recall_unit(wesnoth.get_units({ x= 17, y = 42 })[1], 2)

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on the map, it no longer is. Note: passing a WML table is just a shortcut for calling [[#wesnoth.create_unit]] and then putting the resulting unit on a recall list.

==== wesnoth.create_unit ====

Creates a private unit from a WML table.

local u = wesnoth.create_unit { type = "White Mage", gender = "female" }

==== wesnoth.copy_unit ====

Creates a private unit from another unit.

-- extract a unit from the map
local u = wesnoth.copy_unit(wesnoth.get_units({ type = "Thug" })[1])
wesnoth.put_unit(u.x, u.y)
-- u is still valid at this point

==== wesnoth.extract_unit ====

Removes a unit from the map or from a recall list and makes it private.

-- remove all the units from the recall list of side 1 and put them in a WML container
local l = {}
for i,u in ipairs(wesnoth.get_recall_units { side = 1 }) do
wesnoth.extract_unit(u)
table.insert(l, u.__cfg)
end
helper.set_variable_array("player_recall_list", l)

Note: if the unit is on the map, it is just a shortcut for calling [[#wesnoth.copy_unit]] and then [[#wesnoth.put_unit]] without a unit. It is, however, the only way for removing a unit from a recall list without putting it on the map.

==== wesnoth.add_modification ====

Modifies a given unit. It needs to be a proxy unit. The second argument is the type of the modification (either trait, object, or advance). The option "advance" applies effects as if the unit would advance (e.g. AMLA effects). The third argument is a WML table describing the effect, so mostly containing '''[effect]''' children. See [[EffectWML]] for details about effects.

local u = wesnoth.get_units { canrecruit = true }[1]
wesnoth.add_modification(u, "object", { { "effect", { apply_to = "image_mod", replace = "RC(red>blue)" } } })

==== wesnoth.unit_resistance ====

Returns the resistance of a unit against an attack type. (Note: it is a WML resistance. So the higher it is, the weaker the unit is.) The third argument indicates whether the unit is the attacker. Last arguments are the coordinates of an optional map location (for the purpose of taking abilities into account).

local fire_resistance = 100 - wesnoth.unit_resistance(u, "fire")

==== wesnoth.unit_defense ====

Returns the defense of a unit on a particular terrain. (Note: it is a WML defense. So the higher it is, the weaker the unit is.)

local flat_defense = 100 - wesnoth.unit_defense(u, "Gt")

==== wesnoth.unit_movement_cost ====

Returns the movement cost of a unit on a particular terrain.

local move_cost = wesnoth.unit_movement_cost(u, "Gt")

==== wesnoth.unit_ability ====

Returns true if the unit is currently under effect by an ability with this given TAG NAME. This means that the ability could be owned by the unit itself, or by an adjacent unit.

function has_teleport(u)
return wesnoth.unit_ability(u, "teleport")
end

==== wesnoth.get_unit_type_ids ====
{{DevFeature1.11}}: This function is deprecated, use wesnoth.unit_types.

==== wesnoth.get_unit_type ====
{{DevFeature1.11}}: This function is deprecated, use wesnoth.unit_types instead.

==== wesnoth.unit_types ====

This is not a function but a table indexed by unit type ids. Its elements are the proxy tables returned by [[#wesnoth.get_unit_type]].

local lich_cost = wesnoth.unit_types["Ancient Lich"].cost

==== wesnoth.races ====

This is not a function but a table indexed by race ids. Its elements are proxy tables for all races the engine knows about.
known fields of each element:
* '''id''': string
* '''description''', '''name''', '''plural_name''' (translatable strings)
* '''num_traits''' (integer)
* '''ignore_global_traits''' (boolean)
* '''undead_variation''' (string)
(all read only)
* '''__cfg''': WML table (dump)

wesnoth.message(tostring(wesnoth.races["lizard"].name))

==== wesnoth.get_traits ====

Returns a table with named fields (trait id strings) holding the wml tables defining the traits. arguments: none. All global traits the engine knows about, race-specific traits are not included.
Known fields and subtags of each element are the ones which were given in the wml definition of the [[SingleUnitWML|trait]].
wesnoth.message(tostring(wesnoth.get_traits().strong.male_name))

==== wesnoth.simulate_combat ====

Computes the hitpoint distribution and status chance after a combat between two units. Optional integers can be passed to select a particular weapon, otherwise the "best" one is selected. The first unit is the attacker; it does not have to be on the map, though its location should be meaningful. The second unit is the defender; it has to be on the map.

When giving the attack, the parameter is the attack id (integer) and not an element from the table returned by helper.child_range(att, "attack").

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

==== wesnoth.transform_unit ====

Changes the type of a unit and adjust attributes accordingly. Note that hitpoints might be modified accordingly to the unit type.

local ev = wesnoth.current.event_context
local u = wesnoth.get_units{x=ev.x1, y=ev.y1}[1]
local old_hp = u.hitpoints
wesnoth.transform_unit(u, "Skeleton")
u.hitpoints = old_hp
u.status.poisoned = false

[[Category: Lua Reference]]

LuaWML/Units

2012-02-08T21:58:46Z

Anonymissimus: /* wesnoth.get_unit_type_ids */

This page describes the [[LuaWML]] functions for handling units.

A unit is a proxy table with the following fields:
* '''x''', '''y''': integers (read only, read/write if the unit is not on the map)
* '''side''': integer (read/write)
* '''id''': string (read only)
* '''type''': string (read only)
* '''name''': translatable string (read only)
* '''hitpoints''', '''max_hitpoints''', '''experience''', '''max_experience''', '''max_moves''': integers (read only)
* '''max_attacks''': integer (read only)
* '''attacks_left''': integer (read/write) Setting below 0 is limited to 0.
* '''extra_recruit''': table (read/write)
* '''advances_to''': table (read/write)
* '''hitpoints''', '''experience''': integer (read/write)
* '''moves''': integer (read/write)
* '''resting''': boolean (read/write)
* '''hidden''': boolean (read/write)
* '''petrified''', '''canrecruit''': booleans (read only)
* '''role''', '''facing''': strings (read/write)
* '''status''': proxy associative table (read only, read/write fields)
* '''image_mods''': string (read only)
* '''variables''': proxy associative table (read only, read/write fields, including ''variables.__cfg''), only toplevel named fields are proxied
* '''valid''': string or nil (read only)
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"unit"'''.

A unit can be either visible on the map ([[#wesnoth.get_units]], [[#wesnoth.put_unit]]), or on a recall list ([[#wesnoth.get_recall_units]], [[#wesnoth.put_recall_unit]]), or private to the Lua code ([[#wesnoth.create_unit]], [[#wesnoth.copy_unit]], [[#wesnoth.extract_unit]]). The Lua code has complete control over the private units; they will not be modified unless accessed through the proxy unit. Units on the map and on the recall lists, however, can be modified by the user, the engine, WML, independently of the Lua code. In particular, if a unit is killed, any further use of the proxy unit will cause an error. For units on the map, the proxy unit is valid as long as there is a unit on the map that has the same "underlying_id" WML field as the original one. The behavior is similar for units on the recall lists. The ''valid'' field reflects the unit availability by returning '''"map"''', '''"recall"''', '''"private"''', or ''nil''. The latter value is used for units that were removed (e.g. killed). In that case, the ''valid'' field is the only one that can be read without causing an error.

The term "proxy", here in particular "proxy unit", means that the variable retrieved in the lua code (with get_units for example) is an accessor (reference) to the C++ object which represents that unit. This is very different from unit variables obtained by [store_unit] in wml. The fields marked as "writable" above can be modified without the need to use put_unit afterwards. This same reason explains that modifications to the unit from outside the lua code (like [kill] invalidating the proxy unit) have immediate effect on the lua code's proxy unit variable (with the exception of private proxy units).

==== wesnoth.get_units ====

Returns an array of all the units on the map matching the WML filter passed as the first argument. See [[StandardUnitFilter]] for details about filters.

local leaders_on_side_two = get_units { side = 2, canrecruit = true }
local name_of_leader = leaders_on_side_two[1].name

==== wesnoth.get_unit ====

Returns the unit at the given location or with the given underlying ID.

local args = ...
local unit = wesnoth.get_unit(args.x1, args.y1)

==== wesnoth.match_unit ====

Returns true if the given unit matches the WML filter passed as the second argument.

assert(unit.canrecruit == wesnoth.match_unit(unit, { canrecruit = true }))

==== wesnoth.put_unit ====

Places a unit on the map. This unit is described either by a WML table or by a proxy unit. Coordinates can be passed as the first two arguments, otherwise the table is expected to have two fields '''x''' and '''y''', which indicate where the unit will be placed. If the function is called with coordinates only, the unit on the map at the given coordinates is removed instead.

-- create a unit with random traits, then erase it
wesnoth.put_unit(17, 42, { type = "Elvish Lady" })
wesnoth.put_unit(17, 42)

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on a recall list, it no longer is; and if the unit was on the map, it has been moved to the new location. Note: passing a WML table is just a shortcut for calling [[#wesnoth.create_unit]] and then putting the resulting unit on the map.

-- move the leader back to the top-left corner
wesnoth.put_unit(1, 1, wesnoth.get_units({ canrecruit = true })[1])

==== wesnoth.get_recall_units ====

Returns an array of all the units on the recall lists matching the WML filter passed as the first argument.

==== wesnoth.put_recall_unit ====

Places a unit on a recall list. This unit is described either by a WML table or by a proxy unit. The side of the recall list is given by the second argument, or by the side of the unit if missing.

-- put the unit at location 17,42 on the recall list for side 2
wesnoth.put_recall_unit(wesnoth.get_units({ x= 17, y = 42 })[1], 2)

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on the map, it no longer is. Note: passing a WML table is just a shortcut for calling [[#wesnoth.create_unit]] and then putting the resulting unit on a recall list.

==== wesnoth.create_unit ====

Creates a private unit from a WML table.

local u = wesnoth.create_unit { type = "White Mage", gender = "female" }

==== wesnoth.copy_unit ====

Creates a private unit from another unit.

-- extract a unit from the map
local u = wesnoth.copy_unit(wesnoth.get_units({ type = "Thug" })[1])
wesnoth.put_unit(u.x, u.y)
-- u is still valid at this point

==== wesnoth.extract_unit ====

Removes a unit from the map or from a recall list and makes it private.

-- remove all the units from the recall list of side 1 and put them in a WML container
local l = {}
for i,u in ipairs(wesnoth.get_recall_units { side = 1 }) do
wesnoth.extract_unit(u)
table.insert(l, u.__cfg)
end
helper.set_variable_array("player_recall_list", l)

Note: if the unit is on the map, it is just a shortcut for calling [[#wesnoth.copy_unit]] and then [[#wesnoth.put_unit]] without a unit. It is, however, the only way for removing a unit from a recall list without putting it on the map.

==== wesnoth.add_modification ====

Modifies a given unit. It needs to be a proxy unit. The second argument is the type of the modification (either trait, object, or advance). The option "advance" applies effects as if the unit would advance (e.g. AMLA effects). The third argument is a WML table describing the effect, so mostly containing '''[effect]''' children. See [[EffectWML]] for details about effects.

local u = wesnoth.get_units { canrecruit = true }[1]
wesnoth.add_modification(u, "object", { { "effect", { apply_to = "image_mod", replace = "RC(red>blue)" } } })

==== wesnoth.unit_resistance ====

Returns the resistance of a unit against an attack type. (Note: it is a WML resistance. So the higher it is, the weaker the unit is.) The third argument indicates whether the unit is the attacker. Last arguments are the coordinates of an optional map location (for the purpose of taking abilities into account).

local fire_resistance = 100 - wesnoth.unit_resistance(u, "fire")

==== wesnoth.unit_defense ====

Returns the defense of a unit on a particular terrain. (Note: it is a WML defense. So the higher it is, the weaker the unit is.)

local flat_defense = 100 - wesnoth.unit_defense(u, "Gt")

==== wesnoth.unit_movement_cost ====

Returns the movement cost of a unit on a particular terrain.

local move_cost = wesnoth.unit_movement_cost(u, "Gt")

==== wesnoth.unit_ability ====

Returns true if the unit is currently under effect by an ability with this given TAG NAME. This means that the ability could be owned by the unit itself, or by an adjacent unit.

function has_teleport(u)
return wesnoth.unit_ability(u, "teleport")
end

==== wesnoth.get_unit_type_ids ====
{{DevFeature1.11}}: This function is deprecated, use wesnoth.unit_types.

==== wesnoth.get_unit_type ====

Returns the unit type with the corresponding ID.

local lich_cost = wesnoth.get_unit_type("Ancient Lich").cost

Unit types are proxy tables with the following fields:
* '''id''': string
* '''name''': translatable string (read only)
* '''max_moves''', '''max_experience''', '''max_hitpoints''', '''level''', '''cost''': integers (read only)
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"unit type"'''.

==== wesnoth.unit_types ====

This is not a function but a table indexed by unit type ids. Its elements are the proxy tables returned by [[#wesnoth.get_unit_type]].

local lich_cost = wesnoth.unit_types["Ancient Lich"].cost

==== wesnoth.races ====

This is not a function but a table indexed by race ids. Its elements are proxy tables for all races the engine knows about.
known fields of each element:
* '''id''': string
* '''description''', '''name''', '''plural_name''' (translatable strings)
* '''num_traits''' (integer)
* '''ignore_global_traits''' (boolean)
* '''undead_variation''' (string)
(all read only)
* '''__cfg''': WML table (dump)

wesnoth.message(tostring(wesnoth.races["lizard"].name))

==== wesnoth.get_traits ====

Returns a table with named fields (trait id strings) holding the wml tables defining the traits. arguments: none. All global traits the engine knows about, race-specific traits are not included.
Known fields and subtags of each element are the ones which were given in the wml definition of the [[SingleUnitWML|trait]].
wesnoth.message(tostring(wesnoth.get_traits().strong.male_name))

==== wesnoth.simulate_combat ====

Computes the hitpoint distribution and status chance after a combat between two units. Optional integers can be passed to select a particular weapon, otherwise the "best" one is selected. The first unit is the attacker; it does not have to be on the map, though its location should be meaningful. The second unit is the defender; it has to be on the map.

When giving the attack, the parameter is the attack id (integer) and not an element from the table returned by helper.child_range(att, "attack").

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

==== wesnoth.transform_unit ====

Changes the type of a unit and adjust attributes accordingly. Note that hitpoints might be modified accordingly to the unit type.

local ev = wesnoth.current.event_context
local u = wesnoth.get_units{x=ev.x1, y=ev.y1}[1]
local old_hp = u.hitpoints
wesnoth.transform_unit(u, "Skeleton")
u.hitpoints = old_hp
u.status.poisoned = false

[[Category: Lua Reference]]

LuaWML/Sides

2012-02-08T21:54:26Z

Anonymissimus: /* wesnoth.sides */

This page describes the [[LuaWML]] functions and helpers for handling sides and villages.

==== wesnoth.get_side ====

{{DevFeature1.11}}: This function is deprecated, use wesnoth.sides[i] instead of wesnoth.get_side(i).

==== wesnoth.sides ====

This is not a function but a table indexed by side numbers. Its elements are proxy tables with these fields:
* '''side''': the side number
* '''gold''', '''village_gold''', '''base_income''': integers (read/write)
* '''total_income''': integer (read only)
* '''objectives''', '''user_team_name''': translatable strings (read/write)
* '''objectives_changed''': boolean (read/write)
* '''team_name''': string (read/write)
* '''controller''': string (read/write)
''note: In networked multiplayer, the controller attribute is ambiguous. Be very careful or you have OOS errors.''
* '''fog''': boolean (read)
* '''shroud''': boolean (read)
* '''hidden''': boolean (read)
* '''name''': string (read)
* '''color''': string (read) {{DevFeature1.11}}: also write
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"side"'''.

local team = wesnoth.sides[1]
team.gold = team.gold + 50
wesnoth.message(string.format("%d sides", #wesnoth.sides))

==== wesnoth.get_sides ====

Returns a table array containing proxy tables for these sides matching the passed [[StandardSideFilter]].
--set gold to 0 for all sides with a leader
local sides = wesnoth.get_sides({ {"has_unit", { canrecruit = true }} })
for i,v in ipairs(sides) do
v.gold = 0
end

==== wesnoth.get_village_owner ====

Returns the side that owns the village at the given location.

local owned_by_side_1 = wesnoth.get_village_owner(12, 15) == 1

==== wesnoth.set_village_owner ====

Gives ownership of the village at the given location to the given side (or remove ownership if none). Ownership is also removed if nil or 0 is passed for the third parameter, but no capture events are fired in this case.
An optional 4th parameter (boolean true|false, default: false) can be passed determining whether to fire any capture events.

wesnoth.set_village_owner(12, 15, 1)

==== wesnoth.is_enemy ====

Returns true if side A is enemy of side B, false otherwise.

local enemy_flag = wesnoth.is_enemy(1, 3)

==== wesnoth.match_side ====

Matches a side against a given [[StandardSideFilter]].

wesnoth.message(tostring(wesnoth.match_side(1, {{"has_unit", { type = "Troll" }}})))

==== wesnoth.get_starting_location ====

local loc = wesnoth.get_starting_location(1)
wesnoth.message(string.format("side 1 starts at (%u, %u)", loc[1], loc[2]))

==== helper.all_teams ====

Returns an iterator over teams that can be used in a for-in loop.

for team in helper.all_teams() do team.gold = 200 end

[[Category: Lua Reference]]

LuaWML/Sides

2012-02-08T21:53:22Z

Anonymissimus: /* wesnoth.get_side */

This page describes the [[LuaWML]] functions and helpers for handling sides and villages.

==== wesnoth.get_side ====

{{DevFeature1.11}}: This function is deprecated, use wesnoth.sides[i] instead of wesnoth.get_side(i).

==== wesnoth.sides ====

This is not a function but a table indexed by side numbers. Its elements are the proxy tables returned by [[#wesnoth.get_side]].

local team = wesnoth.sides[1]
team.gold = team.gold + 50
wesnoth.message(string.format("%d sides", #wesnoth.sides))

==== wesnoth.get_sides ====

Returns a table array containing proxy tables for these sides matching the passed [[StandardSideFilter]].
--set gold to 0 for all sides with a leader
local sides = wesnoth.get_sides({ {"has_unit", { canrecruit = true }} })
for i,v in ipairs(sides) do
v.gold = 0
end

==== wesnoth.get_village_owner ====

Returns the side that owns the village at the given location.

local owned_by_side_1 = wesnoth.get_village_owner(12, 15) == 1

==== wesnoth.set_village_owner ====

Gives ownership of the village at the given location to the given side (or remove ownership if none). Ownership is also removed if nil or 0 is passed for the third parameter, but no capture events are fired in this case.
An optional 4th parameter (boolean true|false, default: false) can be passed determining whether to fire any capture events.

wesnoth.set_village_owner(12, 15, 1)

==== wesnoth.is_enemy ====

Returns true if side A is enemy of side B, false otherwise.

local enemy_flag = wesnoth.is_enemy(1, 3)

==== wesnoth.match_side ====

Matches a side against a given [[StandardSideFilter]].

wesnoth.message(tostring(wesnoth.match_side(1, {{"has_unit", { type = "Troll" }}})))

==== wesnoth.get_starting_location ====

local loc = wesnoth.get_starting_location(1)
wesnoth.message(string.format("side 1 starts at (%u, %u)", loc[1], loc[2]))

==== helper.all_teams ====

Returns an iterator over teams that can be used in a for-in loop.

for team in helper.all_teams() do team.gold = 200 end

[[Category: Lua Reference]]