The Battle for Wesnoth Wiki - User contributions [en]

WML Abilities

2024-11-23T21:10:02Z

Name: Events can now be included directly in ability and weapon special tags

The more complex abilities and weapon specials often consist of two parts:
* The ability / weapon special, which is only a dummy to provide a description and to see whether a unit has this ability. It is something one gives to a unit. Mainline abilities / weapon specials only need this part.
* One or multiple [event]s, which make things happen. These can be included directly in the ability or weapon special tag {{DevFeature1.19|4}}. For earlier versions, these [event]s must be added to the game ''explicitly'', in addition to the unit with the ability or weapon special!

How to include [event]s?
* Add it inside the ability or weapon special tag. {{DevFeature1.19|4}}
* Add it directly to the scenario file.
* Add it directly to the [era].
* Add it inside a [unit_type] definition.
* Add it directly in your [campaign] tag.
* Add it inside a [resource], which is then loaded from your [campaign] tag or an individual scenario.
If you add it both via an [era] and and the scenario, they are added twice … i.e. the pickpocket ability would give the gold twice! To avoid that, give each event an '''id'''. This is even mandatory when adding it in a [unit_type].

Even better would be to use a [resource]. Resources have also an id, so there will never be duplicates:
* Instead of adding it to the scenario / era, you add the event code inside a [resource].
* The same way you read the scenario / era file, you also read the file containing the [resource] tag.
* In the scenario / era, use [[ModificationWML#The_.5Bresource.5D_toplevel_tag|load_resource]].

=== Knockback ===

When a unit is hit with a knockback attack, it is immediately pushed back one hex away from the attacker. Units cannot be knocked back into an occupied hex, out of villages or onto terrain they normally could not move to. Only works on offense.

Use this to display the special correctly on the attacks you want:
<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_KNOCKBACK
[dummy]
id=knockback
name= _ "knockback"
female_name= _ "female^knockback"
description=_ "When a unit is hit with a knockback attack, it is immediately pushed back one hex away from the attacker. Units cannot be knocked back into an occupied hex, out of villages or onto terrain they normally could not move to. Only works on offense."
active_on=offense
[/dummy]
#enddef
</syntaxhighlight>

And insert this event to your [scenario], [multiplayer], [unit_type] or [era]:
<syntaxhighlight lang='wml'>
[event]
name=attacker hits
first_time_only=no

[filter_attack]
special_id=knockback
[/filter_attack]

[filter_second]
[not]
[filter_location]
terrain=*^V*
[/filter_location]
[/not]
[/filter_second]

[if]
[variable]
name=second_unit.hitpoints
greater_than=0
[/variable]

[store_locations]
[not]
[filter]
[/filter]
[/not]

[filter_adjacent_location]
x,y=$x2,$y2
adjacent=-$unit.facing
[/filter_adjacent_location]

variable=knockback_target_hex
[/store_locations]

[if]
[variable]
name=knockback_target_hex.length
greater_than=0
[/variable]

[then]
[teleport]
[filter]
x,y=$x2,$y2
[/filter]

x,y=$knockback_target_hex.x,$knockback_target_hex.y
ignore_passability=no
[/teleport]

[if]
[have_unit]
x,y=$knockback_target_hex.x,$knockback_target_hex.y
[/have_unit]

[then]
[sound]
name=fist.ogg
[/sound]

# the knockbacked unit doesn't seem to receive experience by default,
# so we need to add it manually
[store_unit]
[filter]
x,y=$knockback_target_hex.x,$knockback_target_hex.y
[/filter]

kill=yes
variable=knockbacked
[/store_unit]

{VARIABLE_OP knockbacked.experience add $unit.level}

[unstore_unit]
variable=knockbacked
text= _ "knockback"
{COLOR_HARM}
advance=true
[/unstore_unit]

{CLEAR_VARIABLE knockbacked}
[/then]
[/if]
[/then]
[/if]

{CLEAR_VARIABLE knockback_target_hex}
[/then]
[/if]
[/event]
</syntaxhighlight>

=== Charm ===

==== temporary ====

When a unit is hit by a ''charm'' attack, it instantly jumps to the attacker's side, and returns to its original side at the end of the turn. A charmed unit has 1 movement point and can attack.

Example that makes all Troll Whelps have charm on their attack:

{CHARM (type=Troll Whelp) fist}

<syntaxhighlight lang='wml'>
#define CHARM FILTER WEAPON
[event]
name=attacker hits
# Works only as attacker.
# If you want to make a weapon special for this event, set:
# [dummy]active_on=offense, then the engine greys out the weapon special on defense.
first_time_only=no
id=charm_as_attacker

[filter]
{FILTER}
[/filter]

[filter_attack]
name={WEAPON}
# or special_id=charm, if you create a [dummy] weapon special
[/filter_attack]

[filter_second]
# If the leader is charmed, it might end the scenario,
# as the other side is now considered defeated without a leader.
# Better exclude leaders.
canrecruit=no
# If the unit would die from the damage,
# we should not interfere with the event.
formula="self.hitpoints > 0"
[/filter_second]

# Charm the unit
# Changing the side will also immediately stop the combat and grant both units XP
[modify_unit]
[filter]
x,y=$x2,$y2
[/filter]
[variables]
# to remember the original side
real_side=$second_unit.side
[/variables]
[status]
# optional, just to easier find the unit in the other event
charmed=yes
[/status]
side=$unit.side
moves=1
attacks_left=1
[/modify_unit]

[floating_text]
x,y=$x2,$y2
# po: short text, only displayed for a moment
text="<span color='#ffc0cb'>" + _ "charm" + "</span>"
[/floating_text]
[/event]

[event]
name=side turn end, scenario end
# Releasing the unit in the same turn has a few reasons:
# - a charmed unit cannot be charmed again
# - if the scenario ends, we can still correct the ownership
# - things like healing by allies work the usual way
first_time_only=no
id=charm_release

[store_unit]
[filter]
side=$side_number
status=charmed
[/filter]
variable=charmed_units
[/store_unit]

[foreach]
array=charmed_units
[do]
{VARIABLE this_item.side $this_item.variables.real_side}
{CLEAR_VARIABLE this_item.variables.real_side}
{CLEAR_VARIABLE this_item.status.charmed}
[unstore_unit]
variable=this_item
[/unstore_unit]
[/do]
[/foreach]

{CLEAR_VARIABLE charmed_units}
[/event]
#enddef
</syntaxhighlight>

==== permanent ====

This version of the weapon special is a gamble. You can obtain the other unit for good, but you also risk losing this unit. When you lose this unit, the opponent controls a unit with charm. You might regain it when he uses this weapon special.

<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_CHARM
# dummy weapon special used to describe the effect to the user and filter on special's id
[dummy]
id=weapon_charm
name= _ "charm"
description= _ "Turns a living level 1 or level 0 unit to your side. Beware, if all of your attacks miss, the charm user turns to the defender side, even if it is your leader. You can not charm an enemy leader or a non-living creature."
apply_to=opponent
active_on=offense
[/dummy]
#enddef

#define CHARMING_EVENTS
# event that creates a "charm has worked" variable
# and sets it to "yes" if the attacker hits at least once.
[event]
name=attacker_hits
first_time_only=no
id=charm_detect

[filter_attack]
special_id=weapon_charm
[/filter_attack]
[filter_second]
canrecruit=no
level=0,1
[not]
status=unplagueable
[/not]
[/filter_second]

[modify_unit]
[filter]
id=$unit.id
[/filter]
[variables]
charm_has_worked=yes
[/variables]
[/modify_unit]
[/event]

# Event that shifts a unit to the other side,
# if the defending unit:
# - is lvl0 or lvl1
# - and is not a leader unit
# - and is a not a "non-living" creature
# Then:
# -> if the attacker missed all attacks, it goes to the defender’s side.
# -> if the attacker hit once at least, the defender goes to the attacker’s side.
[event]
name=attack_end
first_time_only=no
id=charm_convert

[filter_attack]
special_id=weapon_charm
[/filter_attack]
[filter_second]
canrecruit=no
level=0,1
[not]
status=unplagueable
[/not]
[/filter_second]

[if]
[variable]
name=unit.variables.charm_has_worked
boolean_equals=no
[/variable]
[then]
{VARIABLE unit.side $second_unit.side}
[unstore_unit]
variable=unit
text= _ "Charm failed!"
{COLOR_HARM}
[/unstore_unit]
[/then]
[else]
{VARIABLE second_unit.side $unit.side}
[unstore_unit]
variable=second_unit
text= _ "Charmed!"
{COLOR_HEAL}
[/unstore_unit]

# The variable needs to be unset as well.
{CLEAR_VARIABLE unit.variables.charm_has_worked}
[unstore_unit]
variable=unit
[/unstore_unit]
[/else]
[/if]
[/event]
#enddef
</syntaxhighlight>

=== Bloodlust ===

Bloodlust is a very simple ability. If a unit having bloodlust kills an enemy unit when attacking, it may attack again, provided that there are more enemy units adjacent to it.

This would give the bloodlust ability to all Dwarvish Ulfserkers (making them insanely powerful):

{BLOODLUST (type=Dwarvish Ulfserker)}

<syntaxhighlight lang='wml'>
#define BLOODLUST FILTER
[event]
name=die
first_time_only=no

[filter_second]
{FILTER}
[/filter_second]

[modify_unit]
[filter]
x,y=$x2,$y2
[/filter]
moves=0
attacks_left=1
[/modify_unit]
[/event]
#enddef
</syntaxhighlight>

=== Pickpocket ===

This special could also be called loot. When a unit with this attack special successfully hits an enemy unit, it gains a certain amount of gold.

To do this, use this code:

<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_PICKPOCKET
# Canned definition of the pickpocket ability to be included in a
# [specials] clause.
# dummy weapon special used to describe the effect to the user
# and filter on special's id
[dummy]
id=weapon_pickpocket
name= _ "pickpocket"
description= _ "Gain money for attacking your foe. Each strike scores you one gold."
apply_to=opponent
active_on=offense
[/dummy]
[/specials]
[/attack]

# event that creates a "pickpocket has worked" variable
# and sets it to "yes" if the attacker hits at least once.
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=weapon_pickpocket
[/filter_attack]
[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=unit_att_with_pickpocket
mode=append
[/store_unit]
[set_variable]
name=unit_att_with_pickpocket.variables.pickpocket_has_worked
value=yes
[/set_variable]
[unstore_unit]
variable=unit_att_with_pickpocket
[/unstore_unit]
{CLEAR_VARIABLE unit_att_with_pickpocket}
[/event]
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=weapon_pickpocket
[/filter_attack]
[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=pickpocketer
mode=append
[/store_unit]
[store_unit]
[filter]
x,y=$x2,$y2
[/filter]
variable=pickpocketed
mode=append
[/store_unit]
[if]
[variable]
name=pickpocketer.variables.pickpocket_has_worked
boolean_equals=yes
[/variable]
[then]
[gold]
side=$side_number
amount=2
[/gold]
[unstore_unit]
variable=pickpocketed
text="!"
{COLOR_HEAL}
[/unstore_unit]
[/then]
[/if]
{CLEAR_VARIABLE pickpocketer,pickpocketed}
[/event]
[+attack]
[+specials]
#enddef
</syntaxhighlight>

It can be placed after the [unit_type] tag, or in its own .cfg file.

To change the amount of gold given per hit, change
[gold]
side=$side_number
amount='''X'''
[/gold]
Where '''X''' is the amount of gold you want.

If you want the gold to be constant, given at the end of the turn if at least one of the attack hits, instead of '''X''' amount of gold per hit, change
[event]
'''name=attacker_hits'''
first_time_only=no</code>

to

[event]
'''name=attack_end'''
first_time_only=no

=== Soultaker ===

Any unit with this will gain an additional point of damage per strike every time it kills an enemy. Made for Melon’s Youkai faction (https://r.wesnoth.org/t20100). A variant which uses this as weapon special is used in ageless era (https://r.wesnoth.org/t25274).

One can add this as ability or as weapon special. As ability it will be used when the other unit is killed by any attack of this unit. Using it as weapon special is similar to the Necromancer’s plague staff: It will only take effect when the attack with the special is used to land the killing blow.

Place the following in any .cfg file loaded by the campaign or era:

<syntaxhighlight lang='wml'>
#define SOULTAKER_DUMMY
[dummy]
id=soultaker
name= _ "soultaker"
description=_ "This unit gains an additional point added to its melee damage whenever it kills a living unit."
[/dummy]
#enddef

#define SOULTAKER_EVENT
[event]
name=die
first_time_only=no
id=soultaker

[filter]
[not]
status=undrainable
[/not]
[/filter]

# Use this check if you want to use Soultaker as ability.
[filter_second]
ability=soultaker
[/filter_second]

# To use Soultaker as weapon special, use this check INSTEAD of the above one.
# [filter_second_attack]
# special_id=soultaker
# [/filter_second_attack]

[floating_text]
x,y=$x2,$y2
text="<span color='#00ff00'>" + _ "+1 damage" + "</span>"
[/floating_text]

[object]
silent=yes
duration=forever
[filter]
x,y=$x2,$y2
[/filter]

[effect]
apply_to=attack
increase_damage=1
range=melee
# This will increase all melee attacks by 1. To only increase the attack used in this fight, use
# name=$second_weapon.name
[/effect]
[/object]
[/event]
#enddef
</syntaxhighlight>

And the following in the unit's [abilities] tag. If you changed the code to use the weapon special variant, add instead to the unit’s [attack] an [specials] tag, into which you place:

{SOULTAKER_DUMMY}

Add to the [campaign] or [era] tag:

{SOULTAKER_EVENT}

== Works ==

Unit with ability ''works'' will produce 1 gold per turn. This mechanism is used in the mainline multiplayer map »A New Land«.

Put this macro into you code before the last piece of code.
<syntaxhighlight lang='wml'>
#define ABILITY_WORKS
[works]
id=peasant_works
name="works"
description= _ "This unit produces 1 gold per turn."
[/works]
#enddef
</syntaxhighlight>

Put this event into your code.
<syntaxhighlight lang='wml'>
[event]
name=side turn
first_time_only=no
[store_unit]
[filter]
ability=peasant_works
side=$side_number
[/filter]
variable=workers
[/store_unit]

[foreach]
array=workers
[do]
[gold]
side=$this_item.side
amount=1
[/gold]
[floating_text]
x,y=$this_item.x,$this_item.y
text="<span color='#ffff00'>" + _ "+1 gold" + "</span>"
[/floating_text]
[/do]
[/foreach]

{CLEAR_VARIABLE workers}
[/event]
</syntaxhighlight>

And give the unit the ability like this:
<syntaxhighlight lang='wml'>
[object]
silent=yes
[effect]
apply_to=new_ability
[abilities]
{ABILITY_WORKS}
[/abilities]
[/effect]
[/object]
</syntaxhighlight>

== Mind Flay ==

The weapon special gives an attacker 1 point of exp taken from a defender for each hit. This will violate minimum experience (i.e. defender can go below 0).

Give this special to the attack(s) you want it to have:
<syntaxhighlight lang='wml'>
#define WEAPON_SPECIAL_MIND_FLAY
[mindflay]
id=mind_flay
name= _ "Mind Flay"
description= _ "When used offensively, each hit of the mind flay attack takes 1 point of experience from the defender and gives it to the attacker."
active_on=offense
[/mindflay]
#enddef
</syntaxhighlight>

Include these events into your scenario:
<syntaxhighlight lang='wml'>
[event]
name=attack
first_time_only=no
[filter_attack]
special_id=mind_flay
[/filter_attack]
{VARIABLE hit_number 0}
[/event]
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=mind_flay
[/filter_attack]
{VARIABLE_OP hit_number add 1}
[/event]
[event]
name=attack_end
first_time_only=no
[filter_attack]
special_id=mind_flay
[/filter_attack]
{VARIABLE_OP second_unit.experience sub $hit_number}
{VARIABLE_OP unit.experience add $hit_number}
[unstore_unit]
variable=unit
text=$hit_number
blue=255
[/unstore_unit]
[unstore_unit]
variable=second_unit
[/unstore_unit]
{CLEAR_VARIABLE hit_number}
[/event]
</syntaxhighlight>

== Initiative ==

Initiative is an aura ability. Much like leadership, it affects adjacent allies but not the unit itself.

The ability is used in HttT by Li’sar, you can copy the code from [https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Heir_To_The_Throne/utils/abilities.cfg data/campaigns/Heir_To_The_Throne/utils/abilities.cfg]

== Blitz ==

UtBS and TroW have with ''distract'' an ability, which lets adjacent units ignore the ZoC. It works similar to leadership and initiative, the bonus is valid ''while'' the unit is adjacent.

This ability does the same, but it works similar to healing: The bonus is applied at the beginning of the turn and still valid when not anymore being adjacent.

But it also differs from the way healing works for allied units:
* With healing, it is useful if you move your injured unit to an ally, so that it is adjacent at the healing time.
* With this ability, the unit who wants the bonus must be adjacent at the start of <i>his own</i> turn.

<syntaxhighlight lang='wml'>
#define ABILITY_BLITZ
[dummy]
id=blitz
name= _ "blitz"
description= _ "Allies that start their turn adjacent to this unit are granted skirmisher for that turn."
special_note= _ "Instead of healing other units, this unit grants temporarily skirmisher for allied units at the beginning of their turn."
active_on=offense
affect_self=no
affect_allies=yes
[affect_adjacent][/affect_adjacent]
[/dummy]
#enddef
</syntaxhighlight>

<syntaxhighlight lang='wml'>
#define ABILITY_BLITZ_EVENT
[event]
name=side turn
first_time_only=no

[modify_unit]
# The units adjacent to a unit with the blitz ability …
[filter]
side=$side_number
[filter_adjacent]
is_enemy=no
ability=blitz
[/filter_adjacent]
[/filter]

# … receive temporarily this ability.
[object]
duration=turn end
[effect]
apply_to=new_ability
[abilities]
{ABILITY_SKIRMISHER}
[/abilities]
[/effect]
[/object]
[/modify_unit]
[/event]
#enddef
</syntaxhighlight>

== Immune to drain or plague or poison ==

To make a unit immune to plague, poison or/and draining of life force, set the right [status] for this unit: One or multiple of '''unpoisonable''', '''undrainable''', '''unplagueable'''.

There are many ways to change a status, it can be set directly with [modify_unit], at recruitment via a [trait], or by giving the unit an [object]. In mainline, a [trait] is used to make undead units immune. Traits also have a name and description, which can be used to make it visible to the player that this unit is immune.

<syntaxhighlight lang='wml'>
#define TRAIT_UNDRAINABLE
# We make vampires undrainable with a trait.
# Traits show up in the help browser, thus they should have proper descriptions.
[trait]
id=undrainable
availability=musthave
male_name= _ "vampire"
female_name= _ "female^vampire"
description= _ "This unit’s life force cannot be drained."
help_text= _ "Vampires are like Undead immune to drain and plague, but still susceptible to poison. While this trait is usually seen among vampire units, other mythical beings have also been seen with it. Even some Mages managed to acquire it."
# vampire is not a good name for a trait, as you can give the trait to anybody
[effect]
apply_to=status
add=undrainable
[/effect]
[effect]
apply_to=status
add=unplagueable
[/effect]
[/trait]
#enddef
</syntaxhighlight>

When you define a new [unit'''_type'''], add to it:
{TRAIT_UNDRAINABLE}
num_traits=3 # if you still want it to get 2 other traits

In other cases, if you want to make unit immune, i.e. one from mainline, give it the trait another way:
<syntaxhighlight lang='wml'>
[event]
name=prerecruit
first_time_only=no
[filter]
type_adv_tree=Mage
[or]
race=elf
side=2
[/or]
[/filter]

[modify_unit]
[filter]
id=$unit.id
[/filter]
{TRAIT_UNDRAINABLE}

# Or without trait / object:
# [status]
# undrainable=yes
# [/status]
[/modify_unit]
[/event]
</syntaxhighlight>

== Whirlwind Attack ==

This attack is supposed to be an attack when you spin with your weapons in arms, hitting all nearby enemies, while they cannot counter. It should be used with the magical weapon special, because the spinning weapons are not easy to dodge and the player would pick to attack the unit with the lowest defence without it. It works with drain, slow and poison weapon specials. The attack is supposed to be attack-only, but it can be easily edited to work also on defence.

This is a pair of two macros, one is a weapon special that makes the enemy unable to counter (lowers the number of attacks by 10; for the case if there was a boss or something). The other one is an event that damages the units, that should be placed into every scenario where the unit appears (or the era), preferably through a macro.

This is the part that is the weapon special that marks it:

<syntaxhighlight lang='wml'>
[attacks] #This can be changed to a dummy tag if you don't want it to do anything.
id=whirlwind
name= _ "whirlwind"
description= _ "When this attack is used, all units adjacent the attacker take the damage, and cannot be countered."
value=0
apply_to=opponent
active_on=offense
[/attacks]
</syntaxhighlight>

This is the event:
<syntaxhighlight lang='wml'>
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=whirlwind
[/filter_attack]
{VARIABLE has_drain no} # Notifies the weapon specials
{VARIABLE has_slow no}
{VARIABLE has_poison no}
[if]
[variable]
name=weapon.specials.drains.id
equals=drains
[/variable]
[then]
{VARIABLE has_drain yes}
[/then]
[/if]
[if]
[variable]
name=weapon.specials.poison.id
equals=poison
[/variable]
[then]
{VARIABLE has_poison yes}
[/then]
[/if]
[if]
[variable]
name=weapon.specials.slow.id
equals=slow
[/variable]
[then]
{VARIABLE has_slow yes}
[/then]
[/if]
[if]
[variable]
name=has_drain
boolean_equals=yes
[/variable]
[then]
[store_unit] #We need to know how many units were drained, and what were their resistances
[filter]
[filter_adjacent]
x,y=$x1,$y1
[/filter_adjacent]
[not]
side=$unit.side
[/not]
[not] #The target unit is already hit by the attack
x,y=$x2,$y2
[/not]
[not]
status=undrainable,petrified
[/not]
[/filter]
variable=units
[/store_unit]
{VARIABLE healed_amount 0}
[foreach]
array=units
[do]
[switch] #Check the resistances
variable=weapon.type
[case]
value=arcane
{VARIABLE_OP healed_amount add "$($this_item.resistance.arcane*$weapon.damage)"}
[/case]
[case]
value=fire
{VARIABLE_OP healed_amount add "$($this_item.resistance.fire*$weapon.damage)"}
[/case]
[case]
value=cold
{VARIABLE_OP healed_amount add "$($this_item.resistance.cold*$weapon.damage)"}
[/case]
[case]
value=blade
{VARIABLE_OP healed_amount add "$($this_item.resistance.blade*$weapon.damage)"}
[/case]
[case]
value=pierce
{VARIABLE_OP healed_amount add "$($this_item.resistance.pierce*$weapon.damage)"}
[/case]
[case]
value=impact
{VARIABLE_OP healed_amount add "$($this_item.resistance.impact*$weapon.damage)"}
[/case]
[/switch]
[/do]
[/foreach]
#Float the healed amount over the unit, like if it had drained
[floating_text] #Two numbers will float, the one from the regular hit and one from this
x,y=$x1,$y1 #Operating with huge numbers because rounding is a problem
text="<span color='#00ff00'>" + "$($healed_amount/200)" + "</span>"
[/floating_text]
[heal_unit]
[filter]
x,y=$x1,$y1
[/filter]
amount=$($healed_amount/200)
restore_statuses=no
animate=no
[/heal_unit]
{CLEAR_VARIABLE units,healed_amount}
[/then]
[/if]
[harm_unit]
[filter]
[filter_adjacent]
x,y=$x1,$y1
[/filter_adjacent]
[not]
side=$unit.side
[/not]
[not]
x,y=$x2,$y2
[/not]
[not]
status=petrified
[/not]
[/filter]
[filter_second]
x,y=$x1,$y1
[/filter_second]
amount=$weapon.damage
damage_type=$weapon.type
fire_event=yes
experience=yes #You will have to think about this
poisoned=$has_poison #We have detected these two effects before
slowed=$has_slow
[/harm_unit]
{CLEAR_VARIABLE has_slow,has_poison,has_drain}
[/event]
</syntaxhighlight>

== See Also ==

* [[UsefulWMLFragments]]
* [[ReferenceWML]]

[[Category: UsefulWMLFragments]]

AbilitiesWML

2024-11-23T20:43:37Z

Name: Expand sections about including event tags in ability and weapon special tags

{{WML Tags}}
== Abilities and their effects ==

There are two types of abilities: ones that apply to units (called ''abilities'') and ones that only apply when using a particular attack (called ''specials'' or ''weapon specials''). A unit may have multiple abilities and an attack can have multiple specials.

Each ability or special defines an effect based on one to three units. Most abilities apply to a single unit, and '''[filter_self]''' can be used to determine when the ability is active. Weapon specials apply to two units, which can be filtered either as "attacker" and "defender" (with the obvious meaning) or as "self" and "other" – the unit that possesses the special, and that unit's opponent. When filtering on the "other" unit, you use '''[filter_second]'''.

Leadership-style abilities are a more complex case, as they involve three units. Like a weapon special, there is an attacker and defender, but there is also a third unit that could be referred to as the "teacher". The "teacher" is the unit that possesses the ability, so it is referred to as "self" in the ability. A leadership ability works by temporarily granting a weapon special to either the attacker or the defender. The unit that benefits from this is referred to as the "student", while the unit that does not benefit is simply the "other" unit. When filtering on the "other" unit, you use '''[filter_second]'''.

== The ''[abilities]'' tag ==

The following tags are used to describe an ability in WML:

* '''[heals]''': modifies the hitpoints of a unit at the beginning of the healer's turn
* '''[regenerate]''': modifies the hitpoints of a unit at the beginning of the unit's turn
* '''[resistance]''': modifies the resistance of a unit to damage
* '''[leadership]''': modifies the damage of a unit
* '''[skirmisher]''': negates enemy zones of control
* '''[illuminates]''': modifies the time of day adjacent to the affected units
* '''[teleport]''': allows the unit to teleport
* '''[hides]''': renders the unit invisible to enemies
* {{DevFeature1.15|0}} All [[#The_.5Bspecials.5D_tag|weapon specials]] except for '''[plague]''', '''[heal_on_hit]''', and '''[swarm]''' can be placed in the '''[abilities]''' tag. These [[#Extra_tags_and_keys_used_by_weapon_specials_as_abilities|"weapon specials as abilities"]] will give the weapon special to all attacks the unit has.
* Any other tag is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. '''Note:''' a dummy ability must have an id for the name and description to display.
* {{DevFeature1.15|3}} All the engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== Available formula variables in Abilities and Weapon Specials ===

{{DevFeature1.15|?}} When using formulas in abilities and weapon specials, the following formula variables are available:
* '''self''': (unit) the unit that has the ability
* '''student''': (unit) for leadership-like abilities this is the unit that is adjacent to the unit that has the ability; if affect_self=yes, this is also unit who has ability.
* '''attacker''': (unit) for attack-related abilities and weapon specials, this is the attacking unit during the attack.
* '''defender''': (unit) for attack-related abilities and weapon specials, this is the defending unit during the attack.
* '''other''': (unit) the unit whose stats get modified from the ability. For abilities without 'apply_to=opponent' this is always the same as 'student'.

=== Common keys and tags for every ability ===

{{DevFeature1.13|?}} All keys inside any ability that expects a numeric value will also accept formulas using
[[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses. However, do '''not''' precede those parentheses with a dollar sign like <code>$(...)</code>, since that will erase the <tt>self</tt> variable.

* '''name''': the (translatable) name of the ability. If omitted, the ability will be a hidden ability.
* '''female_name''': the (translatable) name of the ability when possessed by a female unit. Defaults to ''name'' if not specified.
* '''name_inactive''': the (translatable) name of the ability when inactive. Defaults to ''name'' if not specified; if the ability is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''female_name_inactive''': the (translatable) name of the ability when inactive and possessed by a female unit. Defaults to ''name_inactive'' if not specified. You should thus set ''female_name'' as well!
* '''description''': the (translatable) description of the ability.
* '''description_inactive''': the (translatable) description of the ability when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''affect_self''': if equal to 'yes' (default), the ability will affect the unit that has it.
* '''affect_allies''': if equal to 'yes', the ability will affect units from the same and allied sides in the specified adjacent hexes. If set to 'no' it will not affect own or allied sides. If not set (default) it will affect units on the same side but not from allied sides.
* '''affect_enemies''': if equal to 'yes' (default is 'no'), the ability will affect enemies in the specified adjacent hexes.
* '''cumulative''': if set to 'yes', this ability will be cumulative with the base value for this ability. ''Beware of the bug with cumulative leadership in 1.16 https://github.com/wesnoth/wesnoth/issues/6466 , more info see below, in "Extra keys used by the ''leadership'' ability" section''. {{DevFeature1.17|5}}, bug fixed.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''halo_image''': {{DevFeature1.17|22}} if used, the halo specified showed on unit affected by ability.
* '''overlay_image''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit affected by ability.
* '''halo_image_self''': {{DevFeature1.17|22}} if used, the halo specified showed on unit who has ability when active.
* '''overlay_image_self''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit who has ability when active.
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* {{anchor|affect_adjacent|'''[affect_adjacent]'''}}: an adjacent unit that does not match this filter will not receive its effects. There can be multiple [affect_adjacent] tags in a single ability; a unit needs to match any one of these to receive the effects. The side requirement of matching units is defined by the '''affect_allies''' and '''affect_enemies''' keys. If there are no [affect_adjacent] tags, then no adjacent units will receive the effects.
** '''adjacent''': a comma separated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''. (See [[StandardLocationFilter#Directions|notes]])
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
* '''[filter_self]''': if the owner of the ability does not match this filter, it will not receive the effects of the ability. [filter_self] takes a [[StandardUnitFilter]] as argument.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter]. The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location].
* {{anchor|filter_base_value|'''[filter_base_value]'''}}: filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc. If several keys are used all have to match.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} An [event] to be included into any scenario where a unit with this ability appears in. Note that such events get included when a unit with this ability first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[WML_Abilities|WML Abilities]]. Shortcut of [unit_type][event].

=== Extra keys used by the ''[heals]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'',''cured''. ''slowed'' means poison will not take effect for adjacent units (it's not related to the weapon special "slows").

=== Extra keys used by the ''[regenerate]'' ability ===

* '''value''': the amount healed.
* '''poison''': can be one of ''slowed'',''cured''.

=== Extra keys and tags used by the ''[resistance]'' ability ===

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
* '''add''': adds to resistance. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': subtracts from resistance.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''apply_to''': a list of damage types; if left out, the ability applies to all types.
* '''active_on''': one of 'defense' or 'offense'; if left out, the ability is active on both.
These keys affect the actual resistance (e.g. -20%), not the damage modifier normally used in [resistance] (e.g. 120).
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the opponent uses a matching weapon.

=== Extra keys used by the ''[leadership]'' ability ===

* '''value''': the percentage bonus to damage.
* '''add''': the cumulative percentage bonus to damage. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
''Note:'' cumulative leadership with '''cumulative=yes''' and '''value=''' doesn't work in 1.16 (but fixed in 1.17.12 and later). To work around use '''add=''' or '''sub=''' key (it doesn't require cumulative) (https://github.com/wesnoth/wesnoth/issues/6466 ). If you want each instance of a ''[leadership]'' with the same id to be added you will be able to reuse '''cumulative=yes''' in 1.17.12 and later, otherwise, if you want to add the value of another ''[leadership]'' only once even with the same id in several copies, use '''add'''.
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the opponent uses a matching weapon.

=== Extra keys used by the ''[illuminates]'' ability ===

Because this ability changes the terrain instead of units on it, affect_self, affect_allies, affect_enemies and [filter_adjacent] have no effect.
* '''value''': the percentage bonus to lawful units. Units with '''alignment=lawful''' do +''value'' % damage when under the influence of a unit with this ability. Units with '''alignment=chaotic''' do -''value'' % damage. Units with '''alignment=neutral''' are unaffected by this ability. Units with '''alignment=liminal''' do -(abs(''value'')) % damage. ''value'' can be a negative number; this is useful if you want to give Chaotic units an advantage instead of Lawful ones.
* '''add''': the cumulative percentage bonus to damage. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the cumulative percentage bonus subtracted to damage.
* '''multiply''': multiplies resistance value.
* '''divide''': divides resistance value.
* '''max_value''': the maximum percentage bonus given. Cannot be less than 0. Defaults to 0 if not present.
* '''min_value''': the minimum percentage bonus given. Cannot be greater than 0. Defaults to 0 if not present.

=== Extra keys used by the ''[hides]'' ability ===

* '''alert''': the displayed text when the unit is discovered. Default "Ambushed!".

=== Extra tags used by the ''[teleport]'' ability ===

* '''[tunnel]''' - a [[DirectActionsWML#.5Btunnel.5D|tunnel tag]] (without the remove key) defining the tunneling source and target hexes, and maybe other conditions. (It automatically applies only to the unit with the ability.) You may use $teleport_unit inside the [tunnel][source] and [tunnel][target] tag for filtering purposes.

=== Extra tags and keys used by weapon specials as abilities ===

* {{anchor|filter_student|'''[filter_student]'''}}: {{DevFeature1.15|0}} If present, only the unit matching this filter, either the possessor of the ability if affect_self=yes, or an adjacent unit matching '''[filter_adjacent]''' will be affected. '''Replaces''' '''[filter_self]''' of normal weapon specials.
* '''overwrite_specials''': {{DevFeature1.15|13}} If present, allows a special abilities weapon with a numerical value to impose its value and ignore values of abilities or specials of the same type. If '''overwrite_specials=one_side''', the specials and abilities used by the opponent of the unit affected by the ability with this key and applied to it will not be affected. If '''overwrite_specials=both_sides''', all non-key-carrying abilities and all specials of the same type affecting the recipient unit will be affected, even if used by the opponent (used in the macro FORCE_CHANCE_TO_HIT).
* {{anchor|overwrite|'''[overwrite]'''}}: {{DevFeature1.17|22}} Part of '''overwrite_specials'''. Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** {{anchor|filter_specials|'''[experimental_filter_specials]'''}}: [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* ABILITY_AMBUSH
* ABILITY_CURES
* ABILITY_HEALS
* ABILITY_ILLUMINATES
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
* {{DevFeature1.13|2}} ABILITY_LEADERSHIP (replaces the above leadership macros, which are now deprecated)
* ABILITY_NIGHTSTALK
* ABILITY_REGENERATES
* ABILITY_SKIRMISHER
* ABILITY_STEADFAST
* ABILITY_SUBMERGE
* ABILITY_TELEPORT

== The ''[specials]'' tag ==

The '''[specials]''' tag goes inside the '''[attack]''' tag. It can contain the following tags:

* '''[attacks]''': modifies the number of attacks of a weapon, in using '''value''', '''add''', '''sub''', '''multiply''' or '''divide''' attributes
* '''[berserk]''': pushes the attack for more than one combat round, using '''value''' attribute, '''value''' is 1 by default
* '''[chance_to_hit]''': modifies the chance to hit of a weapon, using same standard numerical attributes as '''[attacks]'''
* '''[damage]''': modifies the damage of a weapon, using same attributes as '''[attacks]''' and '''[chance_to_hit]'''
* '''[damage_type]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker half of the damage dealt, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 50% by default
* '''[firststrike]''': forces the weapon to always strike first
* '''[heal_on_hit]''': heals the attacker when an attack connects, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 0 by default
* '''[petrifies]''': turns the target to stone
* '''[plague]''': when used to kill an enemy, a friendly unit takes its place
* '''[poison]''': poisons the target
* '''[slow]''': slows the target
* '''[swarm]''': number of strikes decreases as the unit loses hitpoints
Any other tag is valid, but will result in a special that does nothing but report it is there.

=== Common keys and tags for every weapon special ===

{{DevFeature1.13|?}} All keys inside any weapon special that expects a numeric value will also accept formulas using [[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses.

* '''name''': the (translatable) name of the special. If omitted, the special will be hidden from the player.
* '''name_inactive''': the (translatable) name of the special when inactive. Defaults to ''name'' if not specified; if the special is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''description''': the (translatable) description of the special.
* '''description_inactive''': the (translatable) description of the special when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''id''': this ability will not be cumulative with other specials using this id.
* '''active_on''': one of '''defense''' or '''offense'''; if left out, the special is active on both.
* '''apply_to''': one of '''self''','''opponent''','''attacker''','''defender''','''both''' (default: ''self''). Determines who the effects of this special are applied to.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the special will not be active and no-one will receive its effects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]]. In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_self], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter_self][filter_location][filter_adjacent_location].
* {{anchor|filter_self|'''[filter_self]'''}}: the special will only be active if the owner matches this [[StandardUnitFilter]] (SUF).
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
* {{anchor|filter_opponent|'''[filter_opponent]'''}}: the special will only be active if the opponent matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
* {{anchor|filter_attacker|'''[filter_attacker]'''}}: the special will only be active if the attacker matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
* {{anchor|filter_defender|'''[filter_defender]'''}} the special will only be active if the defender matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.
* '''overwrite_specials''': if equal to 'one_side', then only this unit's specials are evaluated. If equal to 'both_sides', then both this unit's specials and any of the opponent's weapon specials that affect this unit are evaluated. If a special with this attribute is active, it will take precedence over any other specials of the same type that do not have this attribute. Don't applied to boolean weapon special like [poison] ,[slow], [firststrike] or [petrifies].
* '''[overwrite]''': {{DevFeature1.17|22}} Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** '''[experimental_filter_specials]''': [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability], {{DevFeature1.19|5}} [experimental_filter_specials] deprecated, use [filter_specials] instead.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} An [event] to be included into any scenario where a unit with this weapon special appears in. Note that such events get included when a unit with this weapon special first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[WML_Abilities|WML Abilities]]. Shortcut of [unit_type][event].

=== Common keys and tags for specials with a value ===

The '''[damage]''', '''[attacks]''', and '''[chance_to_hit]''' specials take values that specify how those specials modify their respective base values. The '''[drains]''' special takes a value specifying the percentage of damage drained (default 50) and '''[heal_on_hit]''' takes the amount to heal (default 0; negative values will harm the attacker, but not kill).

* '''value''': the value to be used.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]].
* '''sub''': the number to subtract from the base value.
* '''multiply''': this multiplies the base value.
* '''divide''': this divides the base value.
* '''cumulative''': if set to 'yes', this special will be cumulative with the base value.
* '''backstab''': if set to 'yes', this special will only apply to the attacker, and only when there is an enemy on the target's opposite side (i.e. when the standard backstab special applies). {{DevFeature1.13|2}} This is now deprecated. The same functionality can be achieved with a [filter_adjacent] in [filter_opponent]; see the implementation of the default backstab special for details.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.

==== Common calculations ====

Several abilities and weapon specials take the keys '''add''', '''sub''', '''multiply''' and '''divide'''.

{{DevFeature1.19|4}} '''add''' and '''sub''' work independently.

Prior to 1.19.4:

* If '''add''' and '''sub''' are used in the same ability, the '''add''' is ignored
* If '''add''' and '''sub''' are used in separate abilities with the same id, or with the default id that's used when no id is specified, then the order in which the abilities are encountered controls the calculation, which may change depending on units' positions on the map.

=== Extra keys used by the ''[damage_type]'' special ===

{{DevFeature1.17|23}}

* '''replacement_type''': replaces the attack type with the specified type when [damage_type] is active.
* '''alternative_type''': add a second type of attack to the existing type, it is always the one of the two which will do the most damage to the opponent which will be used.

'''Note:''' In 1.18, alternative_type may be stronger than expected, as the damage calculations sometimes ignore [resistance] abilities. This is a known bug, which occurs deterministically and will be left unfixed in 1.18.x to prevent Out Of Sync errors.

'''Note:''' If a [damage_type] special includes a [filter_weapon]type=, that filter is tested against the base type of the weapon, ignoring all [damage_type] specials.

=== Extra keys used by the ''[berserk]'' special ===

* '''value''': the maximum number of combat rounds (default 1).
* '''cumulative''': if set to 'yes', this special will be cumulative with other active berserk specials (on the current combatant, not with an opponent's berserk).

=== Extra keys used by the ''[plague]'' special ===

* '''type''': the unit type to be spawned on kill. When not specified, the default is the unit type of the unit doing the plaguing.

=== Extra keys used by the ''[swarm]'' special ===

* '''swarm_attacks_max''': the maximum number of attacks for the swarm. Defaults to the base number of attacks modified by any applicable [attacks] specials. If this is specified, then the base number of attacks is ignored.
* '''swarm_attacks_min''': the minimum number of attacks for the swarm. Defaults to zero. This can be set higher than swarm_attacks_max to cause a unit to gain attacks as health decreases.
The ratio of the unit's current to maximum hit points will be used to scale the number of attacks between these two values.

Prior to version 1.11, a [swarm] special will cause [attacks] specials to be ignored. In 1.11 and later, [attacks] specials are applied before [swarm].

=== Macros for common weapon specials ===

[https://www.wesnoth.org/macro-reference.html#file:weapon_specials.cfg macro reference]
* WEAPON_SPECIAL_BACKSTAB
* WEAPON_SPECIAL_BERSERK
* WEAPON_SPECIAL_CHARGE
* WEAPON_SPECIAL_DRAIN
* WEAPON_SPECIAL_FIRSTSTRIKE
* WEAPON_SPECIAL_MAGICAL
* WEAPON_SPECIAL_MARKSMAN
* WEAPON_SPECIAL_PLAGUE
* WEAPON_SPECIAL_PLAGUE_TYPE TYPE
* WEAPON_SPECIAL_POISON
* WEAPON_SPECIAL_SLOW
* WEAPON_SPECIAL_STONE
* WEAPON_SPECIAL_SWARM

== See Also ==

* [[UnitTypeWML]]
* [[SingleUnitWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

Winds of Fate

2024-06-29T23:51:53Z

Name: update character sexes

== Introduction ==

This is the walkthrough for the mainline drakes campaign, '''Winds of Fate'''. It was formerly known as '''Wings of Victory''' or '''Wings of Valour'''. It is a hard level campaign with 11 scenarios and 4 levels of difficulty (Easy/Normal/Hard/Nightmare).

=== Synopsis ===
''The story of how the drakes first arrived on the Great Continent.''

'''Note: This walkthrough has many spoilers. Read at your own discretion.'''

== General Strategy ==

In this campaign, the player will have access to all recruits of the MP Default Era's '''Drakes''' faction, but not all at once. Most of the recruit list will unlock with story progression and some unit-trees might be temporarily unavailable due to story reasons. With that being stated, I would suggest prioritizing on the following:

* Get a '''Drake Flare''' and advance it to a '''Drake Flameheart'''. The Leadership ability has predominant value in this campaign as you will mostly be suffering losses throughout since Drakes will mostly get 20%-40% defense on most of the maps (with the exception of the Glider caste, whose defenses range from 30-50). Thus, having a Flameheart to coordinate the attacks of level 2 and level 1 Drakes and Saurians will be paramount to this campaign.
* '''Resha''': This hero-class '''Drake Glider''' will be available for the nine out of the eleven scenarios. Having her advance early to Sky Drake and later to Hurricane Drake is advised. She can be valuable as both a scout and a mixed-fighter.
* '''Gorlack''': The protagonist. He starts at level 1 as a '''Drake Burner'''. He is the only Drake Burner in this campaign to be able to advance to the fearsome and devastating '''Armageddon Drake'''. Feeding him XP should be one of the main focus points of any player of this campaign. Do not worry about any XP deficiency for other units. You will have plenty of chances to farm experience points.
* Saurian Oracles and Saurian Soothsayers. Having these units will benefit you greatly, especially in the last scenario.
* Drake Blademasters. Drake Fighter recruitment is available onwards from scenario 2. Leveling them is recommended as they can dish out big damage during the day, are fast and deadly.
* Drake Arbiters and Wardens. The scenario designs do not really favor the Drake Clasher caste but you can recruit level 2 drakes and saurians at the very end of the campaign so just try to have 2 or 3 arbiters on hand. Drake Thrashers are not that useful in any of the scenarios.
* Fire and Inferno Drakes. These are probably what should be filling your recall list, second only to Drake Warriors and Blademasters. Throughout the campaign, these units will be your main source of damage during the day time schedules.
* Most of the scenarios have "No Gold Carried Over". Thus, do not be shy to get your gold reserves to the negatives.
* Read the [[How to play Drakes|How-To-Play Drakes]] page if you are not familiar with how Drakes are played.

== Scenario 1: The Hunt ==

This is a large map scenario where you start with a set amount of drake units. Burners and Gliders. You can see 2 villages on the map. Try to capture them. They have 1 Drake Warrior and 1 Drake Fighter in them. You have to kill a specific amount of units to win. There are several AI sides, each fighting the other. If you position your drakes carefully, you can get to a farming spot where you can +16 XP per kill (level 2 enemy) units. This is located at the eastern shore of the island. The counter counts for any unit your side kills so try not to kill only level 1 units as you are denying the XP farm you deserve.

== Scenario 2: Reclamation ==

This is the scenario where your drakes will be fighting orcs. You start near the southwestern shore with a few spawned units and Resha. There is an enemy leader nearest to you. Your first task: annihilate that orc and prevent him from recruiting any units after the first turn. Orcs will also recruit "boat" units. These have 0% defense on villages so lure them their and instantly kill them with drakes. One of the southern villages has a Clasher unit. On first dawn, Karron will arrive with her Flight of Drakes. They will be targeting side 3. There is a lore book at the north of the island. You win by accomplishing two things: encircling the enemy orc leader (the orange one) with your drakes and destroying all boat units. Karron's flight will not follow your instructions and try to kill all the orcs so you have to capture the orcish leader first.

For your benefit, it is recommended to try leveling Gorlack here to level 3 or very near it. Same goes for Resha.

== Scenario 2X: Victory Feast ==
Cutscene Only Scenario.
== Scenario 3: The Contention ==

Resha is your only recalled unit in this scenario. You have to defeat Karron or resist until the end of turns. Your recruit list will be subjected to the '''Ways of Morogor'''. To explain it..you can recruit one unit type at a time and then it will reset. You will also have 2 Intendants from the fighter caste (Drake Warrior) and the clasher caste (Drake Thrasher). Karron will have the same (intendants from each other caste). Karron has a Drake Arbiter unit and this should be taken out as soon as possible. It is a real nuisance. The key to victory is having village ownership of 7+ villages at all times and outlasting Karron's units. Do not worry if you lose units here. They get sent to your recall list. You should focus on getting clashers to take out Karron if you manage to reach her.

If you succeed in defeating Karron, you will get an item '''Dragon Claws''' which will give Gorlack a superior melee damage boost.

== Scenario 3X: Final Departure ==

Cutscene Only Scenario.

== Scenario 4: Journey ==
You start with your keep on the southwestern isle. There are enemy merfolk leaders north and east of your location. There are enemy naga as well on the northeastern isle. However, if Resha can get near the naga leader, they will become your allies. Resha can do this effortlessly if she is a level 2 Sky Drake or higher. Using Fire Drakes and Drake Warriors here is recommended. Additionally, if you have Sky Drakes, you can recall them as well. Sky Drake receives a constant 50% defense on this map and is not hindered by deep water. It is imperative to get a good mix of Fire Drakes, Drake Warriors and Sky Drakes in this scenario.

On set intervals (night time), the merfolk leader (the purple one) will summon a Kraken and the naga leader will summon sea serpents. Krakens are menacing to battle and should be lured out of deep water. Try to kill as many Krakens as possible while retaining 100% village ownership. Krakens provide +24 XP to the unit which killed it so take this as an opportunity to get experience drakes (Blademasters, Flamehearts, Inferno and Hurricane Drakes).

The side 2 Merfolk leader is a bit bold. Try to take him out as soon as the scenario starts to make it easier.

Clashers are not available for this scenario (story reasons).

== Scenario 5: Threshold ==

You start of the southwestern edge of the Three Sisters island with some spawned units. There is a loyalist enemy side and several monster sides and an allied saurian side. Try to eradicate that lieutenant on the castle by turn 1 or turn 2. When he dies, the saurians flip over to your side. '''Recruiting and recalling units have been disabled in this scenario.''' There are three temples north of your starting location. Moving units onto them will give you free units (2 saurian augurs, 1 skirmisher, 1 swamp lizard and 1 water serpent and 2 rats). There is no gold carryover and monster spawns are infinite. Try to use this scenario as a means to farm XP for your current set of units. This scenario offers a very good opportunity to get Gorlack to level 4. You win this scenario by capturing all villages so try to delay that and focus on farming some XP.

There is also a lore book at the northern reef of the map.

== Scenario 5X: Early Arrival ==
Cutscene Only Scenario.
== Scenario 6: Landfall ==

In this scenario you have to annihilate all enemy units. Your enemies are the Loyalists. You have access to Clasher recruitment and the clasher caste recalls have been restored to you. There is a beacon right next to your keep/encampment. Lighting it will cause your allies, Karron, her drake flight and the saurians to spawn. Karron's flight will spawn to the west of the human fort and saurians will attack from the north. You have been given the opportunity to time when you wish to light the beacon. Turn 4 is a safe bet to light it. Turn 5 is probably more optimal.

Your enemy will be recruiting an assortment of Loyalist units. The units to watch out for are Longbowmen, Pikemen, Knights and Lancers. These have the most potential of taking out your drakes (and saurians). There are mountains north of your keep. Recruit/recall Drake Clashers/Drake Arbiters and position them on mountains, backed by Fire Drakes and a Soothsayer. Try to lure the human army away from their fort and then light the beacon. Your allies will mostly decimate the fort so you can only focus on the human attack force that was dispatched to fight you.

If you have not already done so, try to level up a Clasher to an Arbiter (Trust me on this).

== Scenario 6X: Winds of Fate ==
Cutscene Only Scenario.
== Scenario 7: Harvest ==

This is perhaps the most controversial scenario of the whole campaign as the tactic employed here is strange. The elves will welcome you in. Recall your most powerful damage dealers. Take your sweet time positioning the units next to each leader. Attack at morning time. Kill all leaders within a single turn. Deal with the rest later.

* For the Ancient Wose leader, Gorlack (he should be a destructive Armageddon Drake by now) and 2 Inferno/Fire drakes are enough.
* For the Elven marshal, 2 Blademasters, 1 Thrasher and 1 Arbiter.
* For the cat, 2 Drake Warriors and maybe a Sky Drake.
* For the mermaid, 1 Drake Warrior, the saurian heroes and Resha.

This scenario has a special mechanic. If your drakes attack an enemy on a forest hex, they will ignite the hex and this fire will spread. Use this to your advantage.

When the Elven Lady dies, she will drop an artifact, the '''Sapphire of Ice'''. This will grant any unit with a ranged cold attack (which increments by level). The best unit to equip this is a Drake Warden/Drake Arbiter. Drake Enforcer/Drake Thrasher (but the extra attack just clutters the side bar UI so maybe not). Any other choice is good, but not as good as the Warden using it.

There is a lore book on the location of the cat "Princess Mew". You should really read it.

== Scenario 8: Overlook ==

The drakes have to escape through a cave. There are elves pursuing you (since you well...you know). Recruit some saurians to delay the elves and recall Fire Drakes and Drake Flares to navigate one of the tunnels. There is lore book inside the left tunnel. You will encounter undead inside these caves. Dispatch the Death Knight leader quickly and proceed onwards.

You will encounter an Ancient Lich who can recruit Liches and Spectres. However, if you attack it directly, it offers you a truce which you can accept or refuse. The choice is up to you. However, forming a truce has a better benefit. It will open the escape route and delay the elves.

You have the chance to farm the level 3 elves for XP but it is a bit risky as there are Sylphs which can easily take out drakes and move relatively faster in caves. Retreat through the cave, remembering that Resha should be the last unit to escape.

== Scenario 9: Ancestor ==

You start on a Keep/Encampment with the Saurian heroine units. You might have enough gold for 9 recalls (might be different by difficulty). The terrain is mostly snowy and swampy. There are monster units battling each other everywhere. Perfect farming spot.

=== Recall Priority: ===
* Hurricane/Sky Drakes: Best recallable option. Snowy Terrain? No problem. They will just fly over most terrain without any movement impediments at all.
* Drake Warriors: You can never go wrong with Drake Warriors.
* Fire Drakes. Two or more.
* Drake Flameheart: Only if you have a bunch of level 2 drakes recalled and can level up.
* One Saurian Soothsayer (to supplement Zedrix in healing). Optional.
* One Saurian Ambusher (she can level up fast here). Optional.

=== Ignore ===
* Drake Clasher caste recalls. It is a shame that the campaign's design does not encourage usage of clashers in most scenarios.
* Saurian Oracles. Most monsters are cold resistant, so might have these units sit this one out.

=== Monster Priority ===
* Yeti: Dangerous to confront without adequate support. 32 XP on kill so should be dealt with if encountered.
* Greater Icemonax: Probably has a masters degree in being the most annoying. resistant to most damage types. Avoid if able since you can get better kills here.
* Dread Bat: One Word. Annoying.
* Gryphon. Has a high chance of spawning next to your keep at start.
* Direwolf: perfect for XP farm.
* Cave Bear: good farm option

Your goal is get Gorlack to the beacon on top of the volcanic mountain range. Once there, you will meet a dragon and his wyrms. Then they will become your allies and finally, you have purge the map of all enemies.

== Scenario 10: Fire Meets Steel ==

You start at a new eerie establish on the volcanic mountain range. '''You can recruit level 2 drakes and saurians'''. At this point, your recruit list is now identical to the '''Age of Heroes''' Era's Drakes faction. Your enemies are dwarves.

In this scenario you have to resist the dwarven offensive for three days (18 turns). Here, recalling 2 Hurricane Drakes is obligatory for the swift victory tactics. Recall your loyal intendants and a Flameheart. Recruit Clashers and Burners, but prioritize on Drake Clasher recruitment. Losing a village deprives of +4 income so you should be focusing on retaining most of the villages.

Dwarven Thunderguards, Stalwarts and Berserkers should be approached with caution as they can gang up on your units. The dwarves also spawn from the mountain tunnels and the leader himself will be sending Gryphon Riders and Gryphon Masters This is where your Hurricane drakes come in. Send them to circumvent the enemy and collapse the tunnels. That way the subsequent waves will have less units to deal with. Keep the dwarves at bay by exploiting the mobility of the drakes and the lava reef.

At the end of the scenario, Resha is returned to you.

== Scenario 11: Crosswind ==

The final scenario. Your enemy is the remnants of the Flight of Karron. The victory objective is surrounding Karron with 6 of your units. Additionally, the Saurian Flanker heroine (it's a she)...will turn on you. Oh, no! A spoiler! Deal with it.

The key to this scenario is Resha herself.

Turn 1: Send Resha south to visit the coastal villages. Landing a unit on some of these villages will spawn allies (veteran Nagas and Saurians, and swamp affinity monster units). There is another village near the mountain that does another spawn.
Likewise, recall another Hurricane Drake and send it to the village at the western/left edge of the map. The village spawns 1 troll, a giant spider and an greater icemonax.

Once Resha has captured the 2 villages, rush all your spawned saurians, and monsters towards Karron. Resha should be heading to Karron's keep and nullifying any chances of her recruiting. This is a bit tricky but doable.

=== Recall Priority ===
* Drake Blademasters. Probably the best units for this campaigns you can have. Recall all of them. Every single one.
* Drake Warden with Sapphire Orb.
* Saurian Oracles (as many as you got). Recruit if you lost all of them.
* A Drake Flameheart (to supplement the Oracles)
* Saurian Flankers

There are 2 lore tablets/secrets here (northeast and southeast of the starting keep).

Karron will spawn her Burner caste veterans and Glider caste veterans when she is attacked. Keep this in mind.

Once Resha occupies the keep, Karron will not go for the keep, instead she will move to attack whatever she sees. This is a good moment to get her surrounded as your skirmishing flankers and swamp lizards are already there with nagas.

For the honorable way, just let Karron walk to her keep, while occupying the 5 adjacent hexes of the keep so when she moves, she will recruit just 1 unit and then on your turn, kill that unit and place your unit to capture her.

== Scenario 12: Epilogue ==
Cutscene Only Scenario.

[[Category: Campaigns - Walkthroughs]]
[[Category: Campaigns - Winds of Fate]]

Winds of Fate

2024-06-29T23:19:44Z

Name:

== Introduction ==

This is the walkthrough for the mainline drakes campaign, '''Winds of Fate'''. It was formerly known as '''Wings of Victory''' or '''Wings of Valour'''. It is a hard level campaign with 11 scenarios and 4 levels of difficulty (Easy/Normal/Hard/Nightmare).

=== Synopsis ===
''The story of how the drakes first arrived on the Great Continent.''

'''Note: This walkthrough has many spoilers. Read at your own discretion.'''

== General Strategy ==

In this campaign, the player will have access to all recruits of the MP Default Era's '''Drakes''' faction, but not all at once. Most of the recruit list will unlock with story progression and some unit-trees might be temporarily unavailable due to story reasons. With that being stated, I would suggest prioritizing on the following:

* Get a '''Drake Flare''' and advance him to a '''Drake Flameheart'''. The Leadership ability has predominant value in this campaign as you will mostly be suffering losses throughout since Drakes will mostly get 20%-40% defense on most of the maps (with the exception of the Glider caste, whose defenses range from 30-50). Thus, having a Flameheart to coordinate the attacks of level 2 and level 1 Drakes and Saurians will be paramount to this campaign.
* '''Reshan''': This hero-class '''Drake Glider''' will be available for the nine out of the eleven scenarios. Having him advance early to Sky Drake and later to Hurricane Drake is advised. He can be valuable as both a scout and a mixed-fighter.
* '''Gorlack''': The protagonist. He starts at level 1 as a '''Drake Burner'''. He is the only Drake Burner in this campaign to be able to advance to the fearsome and devastating '''Armageddon Drake'''. Feeding him XP should be one of the main focus points of any player of this campaign. Do not worry about any XP deficiency for other units. You will have plenty of chances to farm experience points.
* Saurian Oracles and Saurian Soothsayers. Having these units will benefit you greatly, especially in the last scenario.
* Drake Blademasters. Drake Fighter recruitment is available onwards from scenario 2. Levelling them is recommended as they can dish out big damage during the day, are fast and deadly.
* Drake Arbiters and Wardens. The scenario designs do not really favor the Drake Clasher caste but you can recruit level 2 drakes and saurians at the very end of the campaign so just try to have 2 or 3 arbiters on hand. Drake Thrashers are not that useful in any of the scenarios.
* Fire and Inferno Drakes. These are probably what should be filling your recall list, second only to Drake Warriors and Blademasters. Throughout the campaign, these units will be your main source of damage during the day time schedules.
* Most of the scenarios have "No Gold Carried Over". Thus, do not be shy to get your gold reserves to the negatives.
* Read the [[How to play Drakes|How-To-Play Drakes]] page if you are not familiar with how Drakes are played.

== Scenario 1: The Hunt ==

This is a large map scenario where you start with a set amount of drake units. Burners and Gliders. You can see 2 villages on the map. Try to capture them. They have 1 Drake Warrior and 1 Drake Fighter in them. You have to kill a specific amount of units to win. There are several AI sides, each fighting the other. If you position your drakes carefully, you can get to a farming spot where you can +16 XP per kill (level 2 enemy) units. This is located at the eastern shore of the island. The counter counts for any unit your side kills so try not to kill only level 1 units as you are denying the XP farm you deserve.

== Scenario 2: Reclamation ==

This is the scenario where your drakes will be fighting orcs. You start near the southwestern shore with a few spawned units and Reshan. There is an enemy leader nearest to you. Your first task: annihilate that orc and prevent him from recruiting any units after the first turn. Orcs will also recruit "boat" units. These have 0% defense on villages so lure them their and instantly kill them with drakes. One of the southern villages has a Clasher unit. On first dawn, Karron will arrive with his Flight of Drakes. They will be targeting side 3. There is a lore book at the north of the island. You win by accomplishing two things: encircling the enemy orc leader (the orange one) with your drakes and destroying all boat units. Karron's flight will not follow your instructions and try to kill all the orcs so you have to capture the orcish leader first.

For your benefit, it is recommended to try levelling Gorlack here to level 3 or very near it. Same goes for Reshan.

== Scenario 2X: Victory Feast ==
Cutscene Only Scenario.
== Scenario 3: The Contention ==

Reshan is your only recalled unit in this scenario. You have to defeat Karron or resist until the end of turns. Your recruit list will be subjected to the '''Ways of Morogor'''. To explain it..you can recruit one unit type at a time and then it will reset. You will also have 2 Intendants from the fighter caste (Drake Warrior) and the clasher caste (Drake Thrasher). Karron will have the same (intendants from each other caste). Karron has a Drake Arbiter unit and this should be taken out as soon as possible. He is a real nuisance. The key to victory is having village ownership of 7+ villages at all times and outlasting Karron's units. Do not worry if you lose units here. They get sent to your recall list. You should focus on getting clashers to take out Karron if you manage to reach him.

If you succeed in defeating Karron, you will get an item '''Dragon Claws''' which will give Gorlack a superior melee damage boost.

== Scenario 3X: Final Departure ==

Cutscene Only Scenario.

== Scenario 4: Journey ==
You start with your keep on the southwestern isle. There are enemy merfolk leaders north and east of your location. There are enemy naga as well on the northeastern isle. However, if Reshan can get near the naga leader, they will become your allies. Reshan can do this effortlessly if he is a level 2 Sky Drake or higher. Using Fire Drakes and Drake Warriors here is recommended. Additionally, if you have Sky Drakes, you can recall them as well. Sky Drake receives a constant 50% defense on this map and is not hindered by deep water. It is imperative to get a good mix of Fire Drakes, Drake Warriors and Sky Drakes in this scenario.

On set intervals (night time), the merfolk leader (the purple one) will summon a Kraken and the naga leader will summon sea serpents. Krakens are menacing to battle and should be lured out of deep water. Try to kill as many Krakens as possible while retaining 100% village ownership. Krakens provide +24 XP to the unit which killed it so take this as an opportunity to get experience drakes (Blademasters, Flamehearts, Inferno and Hurricane Drakes).

The side 2 Merfolk leader is a bit bold. Try to take him out as soon as the scenario starts to make it easier.

Clashers are not available for this scenario (story reasons).

== Scenario 5: Threshold ==

You start of the southwestern edge of the Three Sisters island with some spawned units. There is a loyalist enemy side and several monster sides and an allied saurian side. Try to eradicate that lieutenant on the castle by turn 1 or turn 2. When he dies, the saurians flip over to your side. '''Recruiting and recalling units have been disabled in this scenario.''' There are three temples north of your starting location. Moving units onto them will give you free units (2 saurian augurs, 1 skirmisher, 1 swamp lizard and 1 water serpent and 2 rats). There is no gold carryover and monster spawns are infinite. Try to use this scenario as a means to farm XP for your current set of units. This scenario offers a very good opportunity to get Gorlack to level 4. You win this scenario by capturing all villages so try to delay that and focus on farming some XP.

There is also a lore book at the northern reef of the map.

== Scenario 5X: Early Arrival ==
Cutscene Only Scenario.
== Scenario 6: Landfall ==

In this scenario you have to annihilate all enemy units. Your enemies are the Loyalists. You have access to Clasher recruitment and the clasher caste recalls have been restored to you. There is a beacon right next to your keep/encampment. Lighting it will cause your allies, Karron, his drake flight and the saurians to spawn. Karron's flight will spawn to the west of the human fort and saurians will attack from the north. You have been given the opportunity to time when you wish to light the beacon. Turn 4 is a safe bet to light it. Turn 5 is probably more optimal.

Your enemy will be recruiting an assortment of Loyalist units. The units to watch out for are Longbowmen, Pikemen, Knights and Lancers. These have the most potential of taking out your drakes (and saurians). There are mountains north of your keep. Recruit/recall Drake Clashers/Drake Arbiters and position them on mountains, backed by Fire Drakes and a Soothsayer. Try to lure the human army away from their fort and then light the beacon. Your allies will mostly decimate the fort so you can only focus on the human attack force that was dispatched to fight you.

If you have not already done so, try to level up a Clasher to an Arbiter (Trust me on this).

== Scenario 6X: Winds of Fate ==
Cutscene Only Scenario.
== Scenario 7: Harvest ==

This is perhaps the most controversial scenario of the whole campaign as the tactic employed here is strange. The elves will welcome you in. Recall your most powerful damage dealers. Take your sweet time positioning the units next to each leader. Attack at morning time. Kill all leaders within a single turn. Deal with the rest later.

* For the Ancient Wose leader, Gorlack (he should be a destructive Armageddon Drake by now) and 2 Inferno/Fire drakes are enough.
* For the Elven marshal, 2 Blademasters, 1 Thrasher and 1 Arbiter.
* For the cat, 2 Drake Warriors and maybe a Sky Drake.
* For the mermaid, 1 Drake Warrior, the saurian heroes and Reshan.

This scenario has a special mechanic. If your drakes attack an enemy on a forest hex, they will ignite the hex and this fire will spread. Use this to your advantage.

When the Elven Lady dies, she will drop an artifact, the '''Sapphire of Ice'''. This will grant any unit with a ranged cold attack (which increments by level). The best unit to equip this is a Drake Warden/Drake Arbiter. Drake Enforcer/Drake Thrasher (but the extra attack just clutters the side bar UI so maybe not). Any other choice is good, but not as good as the Warden using it.

There is a lore book on the location of the cat "Princess Mew". You should really read it.

== Scenario 8: Overlook ==

The drakes have to escape through a cave. There are elves pursuing you (since you well...you know). Recruit some saurians to delay the elves and recall Fire Drakes and Drake Flares to navigate one of the tunnels. There is lore book inside the left tunnel. You will encounter undead inside these caves. Dispatch the Death Knight leader quickly and proceed onwards.

You will encounter an Ancient Lich who can recruit Liches and Spectres. However, if you attack him, you are prompted to form a truce or destroy him. The choice is up to you. However, forming a truce has a better benefit. He will open the escape route and delay the elves.

You have the chance to farm the level 3 elves for XP but it is a bit risky as there are Sylphs which can easily take out drakes and move relatively faster in caves. Retreat through the cave, remembering that Reshan should be the last unit to escape.

== Scenario 9: Ancestor ==

You start on a Keep/Encampment with the Saurian heroine units. You might have enough gold for 9 recalls (might be different by difficulty). The terrain is mostly snowy and swampy. There are monster units battling each other everywhere. Perfect farming spot.

=== Recall Priority: ===
* Hurricane/Sky Drakes: Best recallable option. Snowy Terrain? No problem. They will just fly over most terrain without any movement impediments at all.
* Drake Warriors: You can never go wrong with Drake Warriors.
* Fire Drakes. Two or more.
* Drake Flameheart: Only if you have a bunch of level 2 drakes recalled and can level up.
* One Saurian Soothsayer (to supplement Zedrix in healing). Optional.
* One Saurian Ambusher (she can level up fast here). Optional.

=== Ignore ===
* Drake Clasher caste recalls. It is a shame that the campaign's design does not encourage usage of clashers in most scenarios.
* Saurian Oracles. Most monsters are cold resistant, so might have these units sit this one out.

=== Monster Priority ===
* Yeti: Dangerous to confront without adequate support. 32 XP on kill so should be dealt with if encountered.
* Greater Icemonax: Probably has a masters degree in being the most annoying. resistant to most damage types. Avoid if able since you can get better kills here.
* Dread Bat: One Word. Annoying.
* Gryphon. Has a high chance of spawning next to your keep at start.
* Direwolf: perfect for XP farm.
* Cave Bear: good farm option

Your goal is get Gorlack to the beacon on top of the volcanic mountain range. Once there, you will meet a dragon and his wyrms. Then they will become your allies and finally, you have purge the map of all enemies.

== Scenario 10: Fire Meets Steel ==

You start at a new eerie establish on the volcanic mountain range. '''You can recruit level 2 drakes and saurians'''. At this point, your recruit list is now identical to the '''Age of Heroes''' Era's Drakes faction. Your enemies are dwarves.

In this scenario you have to resist the dwarven offensive for three days (18 turns). Here, recalling 2 Hurricane Drakes is obligatory for the swift victory tactics. Recall your loyal intendants and a Flameheart. Recruit Clashers and Burners, but prioritize on Drake Clasher recruitment. Losing a village deprives of +4 income so you should be focusing on retaining most of the villages.

Dwarven Thunderguards, Stalwarts and Berserkers should be approached with caution as they can gang up on your units. The dwarves also spawn from the mountain tunnels and the leader himself will be sending Gryphon Riders and Gryphon Masters This is where your Hurricane drakes come in. Send them to circumvent the enemy and collapse the tunnels. That way the subsequent waves will have less units to deal with. Keep the dwarves at bay by exploiting the mobility of the drakes and the lava reef.

At the end of the scenario, Reshan is returned to you.

== Scenario 11: Crosswind ==

The final scenario. Your enemy is the remnants of the Flight of Karron. The victory objective is surrounding Karron with 6 of your units. Additionally, the Saurian Flanker heroine (it's a she)...will turn on you. Oh, no! A spoiler! Deal with it.

The key to this scenario is Reshan himself.

Turn 1: Send Reshan south to visit the coastal villages. Landing a unit on some of these villages will spawn allies (veteran Nagas and Saurians, and swamp affinity monster units). There is another village near the mountain that does another spawn.
Likewise, recall another Hurricane Drake and send him to the village at the western/left edge of the map. The village spawns 1 troll, a giant spider and an greater icemonax.

Once Reshan has captured the 2 villages, rush all your spawned saurians, and monsters towards Karron. Reshan should be heading to Karron's keep and nullifying any chances of him recruiting. This is a bit tricky but doable.

=== Recall Priority ===
* Drake Blademasters. Probably the best units for this campaigns you can have. Recall all of them. Every single one.
* Drake Warden with Sapphire Orb.
* Saurian Oracles (as many as you got). Recruit if you lost all of them.
* A Drake Flameheart (to supplement the Oracles)
* Saurian Flankers

There are 2 lore tablets/secrets here (northeast and southeast of the starting keep).

Karron will spawn his Burner caste veterans and Glider caste veterans when he is attacked. Keep this in mind.

Once Reshan occupies the keep, Karron will not go for the keep, instead he will move to attacking to whatever he sees. This is a good moment to get him surrounded as your skirmishing flankers and swamp lizards are already there with nagas.

For the honorable way, just let Karron walk to his keep, while occupying the 5 adjacent hexes of the keep so when he moves, he will recruit just 1 unit and then on your turn, kill that unit and place your unit to capture him.

== Scenario 12: Epilogue ==
Cutscene Only Scenario.

[[Category: Campaigns - Walkthroughs]]
[[Category: Campaigns - Winds of Fate]]

Winds of Fate

2024-06-29T23:11:50Z

Name: updated difficulty names

== Introduction ==

This is the walkthrough for the mainline drakes campaign, '''Winds of Fate'''. It was formerly known as '''Wings of Victory''' or '''Wings of Valour'''. It is a hard level campaign with 11 scenarios and 4 levels of difficulty (Easy/Normal/Hard/Nightmare).

=== Synopsis ===
''The story of how the drakes first arrived on the Great Continent.''

'''Note: This walkthrough has many spoilers. Read at your own discretion.'''

== General Strategy ==

In this campaign, the player will have access to all recruits of the MP Default Era's '''Drakes''' faction, but not all at once. Most of the recruit list will unlock with story progression and some unit-trees might be temporarily unavailable due to story reasons. With that being stated, I would suggest prioritizing on the following:

* Get a '''Drake Flare''' and advance him to a '''Drake Flameheart'''. The Leadership ability has predominant value in this campaign as you will mostly be suffering losses throughout since Drakes will mostly get 20%-40% defense on most of the maps (with the exception of the Glider caste, whose defenses range from 30-50). Thus, having a Flameheart to coordinate the attacks of level 2 and level 1 Drakes and Saurians will be paramount to this campaign.
* '''Reshan''': This hero-class '''Drake Glider''' will be available for the nine out of the eleven scenarios. Having him advance early to Sky Drake and later to Hurricane Drake is advised. He can be valuable as both a scout and a mixed-fighter.
* '''Gorlack''': The protagonist. He starts at level 1 as a '''Drake Burner'''. He is the only Drake Burner in this campaign to be able to advance to the fearsome and devastating '''Armageddon Drake'''. Feeding him XP should be one of the main focus points of any player of this campaign. Do not worry about any XP deficiency for other units. You will have plenty of chances to farm experience points.
* Saurian Oracles and Saurian Soothsayers. Having these units will benefit you greatly, especially in the last scenario.
* Drake Blademasters. Drake Fighter recruitment is available onwards from scenario 2. Levelling them is recommended as they can dish out big damage during the day, are fast and deadly.
* Drake Arbiters and Wardens. The scenario designs do not really favor the Drake Clasher caste but you can recruit level 2 drakes and saurians at the very end of the campaign so just try to have 2 or 3 arbiters on hand. Drake Thrashers are not that useful in any of the scenarios.
* Fire and Inferno Drakes. These are probably what should be filling your recall list, second only to Drake Warriors and Blademasters. Throughout the campaign, these units will be your main source of damage during the day time schedules.
* Most of the scenarios have "No Gold Carried Over". Thus, do not be shy to get your gold reserves to the negatives.
* Read the [[How to play Drakes|How-To-Play Drakes]] page if you are not familiar with how Drakes are played.

== Scenario 1: The Hunt ==

This is a large map scenario where you start with a set amount of drake units. Burners and Gliders. You can see 2 villages on the map. Try to capture them. They have 1 Drake Warrior and 1 Drake Fighter in them. You have to kill a specific amount of units to win. There are several AI sides, each fighting the other. If you position your drakes carefully, you can get to a farming spot where you can +16 XP per kill (level 2 enemy) units. This is located at the eastern shore of the island. The counter counts for any unit your side kills so try not to kill only level 1 units as you are denying the XP farm you deserve.

== Scenario 2: Reclamation ==

This is the scenario where your drakes will be fighting orcs. You start near the southwestern shore with a few spawned units and Reshan. There is an enemy leader nearest to you. Your first task: annihilate that orc and prevent him from recruiting any units after the first turn. Orcs will also recruit "boat" units. These have 0% defense on villages so lure them their and instantly kill them with drakes. One of the southern villages has a Clasher unit. On first dawn, Karron will arrive with his Flight of Drakes. They will be targeting side 3. There is a lore book at the north of the island. You win by accomplishing two things: encircling the enemy orc leader (the orange one) with your drakes and destroying all boat units. Karron's flight will not follow your instructions and try to kill all the orcs so you have to capture the orcish leader first.

For your benefit, it is recommended to try levelling Gorlack here to level 3 or very near it. Same goes for Reshan.

== Scenario 2X: Victory Feast ==
Cutscene Only Scenario.
== Scenario 3: The Contention ==

Reshan is your only recalled unit in this scenario. You have to defeat Karron or resist until the end of turns. Your recruit list will be subjected to the '''Ways of Morogor'''. To explain it..you can recruit one unit type at a time and then it will reset. You will also have 2 Intendants from the fighter caste (Drake Warrior) and the clasher caste (Drake Thrasher). Karron will have the same (intendants from each other caste). Karron has a Drake Arbiter unit and this should be taken out as soon as possible. He is a real nuisance. The key to victory is having village ownership of 7+ villages at all times and outlasting Karron's units. Do not worry if you lose units here. They get sent to your recall list. You should focus on getting clashers to take out Karron if you manage to reach him.

If you succeed in defeating Karron, you will get an item '''Dragon Claws''' which will give Gorlack a superior melee damage boost.

== Scenario 3X: Final Departure ==

Cutscene Only Scenario.

== Scenario 4: Journey ==
You start with your keep on the southwestern isle. There are enemy merfolk leaders north and east of your location. There are enemy naga as well on the northeastern isle. However, if Reshan can get near the naga leader, they will become your allies. Reshan can do this effortlessly if he is a level 2 Sky Drake or higher. Using Fire Drakes and Drake Warriors here is recommended. Additionally, if you have Sky Drakes, you can recall them as well. Sky Drake receives a constant 50% defense on this map and is not hindered by deep water. It is imperative to get a good mix of Fire Drakes, Drake Warriors and Sky Drakes in this scenario.

On set intervals (night time), the merfolk leader (the purple one) will summon a Kraken and the naga leader will summon sea serpents. Krakens are menacing to battle and should be lured out of deep water. Try to kill as many Krakens as possible while retaining 100% village ownership. Krakens provide +24 XP to the unit which killed it so take this as an opportunity to get experience drakes (Blademasters, Flamehearts, Inferno and Hurricane Drakes).

The side 2 Merfolk leader is a bit bold. Try to take him out as soon as the scenario starts to make it easier.

Clashers are not available for this scenario (story reasons).

== Scenario 5: Threshold ==

You start of the southwestern edge of the Three Sisters island with some spawned units. There is a loyalist enemy side and several monster sides and an allied saurian side. Try to eradicate that lieutenant on the castle by turn 1 or turn 2. When he dies, the saurians flip over to your side. '''Recruiting and recalling units have been disabled in this scenario.''' There are three temples north of your starting location. Moving units onto them will give you free units (2 saurian augurs, 1 skirmisher, 1 swamp lizard and 1 water serpent and 2 rats). There is no gold carryover and monster spawns are infinite. Try to use this scenario as a means to farm XP for your current set of units. This scenario offers a very good opportunity to get Gorlack to level 4. You win this scenario by capturing all villages so try to delay that and focus on farming some XP.

There is also a lore book at the northern reef of the map.

== Scenario 5X: Early Arrival ==
Cutscene Only Scenario.
== Scenario 6: Landfall ==

In this scenario you have to annihilate all enemy units. Your enemies are the Loyalists. You have access to Clasher recruitment and the clasher caste recalls have been restored to you. There is a beacon right next to your keep/encampment. Lighting it will cause your allies, Karron, his drake flight and the saurians to spawn. Karron's flight will spawn to the west of the human fort and saurians will attack from the north. You have been given the opportunity to time when you wish to light the beacon. Turn 4 is a safe bet to light it. Turn 5 is probably more optimal.

Your enemy will be recruiting an assortment of Loyalist units. The units to watch out for are Longbowmen, Pikemen, Knights and Lancers. These have the most potential of taking out your drakes (and saurians). There are mountains north of your keep. Recruit/recall Drake Clashers/Drake Arbiters and position them on mountains, backed by Fire Drakes and a Soothsayer. Try to lure the human army away from their fort and then light the beacon. Your allies will mostly decimate the fort so you can only focus on the human attack force that was dispatched to fight you.

If you have not already done so, try to level up a Clasher to an Arbiter (Trust me on this).

== Scenario 6X: Winds of Fate ==
Cutscene Only Scenario.
== Scenario 7: Harvest ==

This is perhaps the most controversial scenario of the whole campaign as the tactic employed here is strange. The elves will welcome you in. Recall your most powerful damage dealers. Take your sweet time positioning the units next to each leader. Attack at morning time. Kill all leaders within a single turn. Deal with the rest later.

* For the Ancient Wose leader, Gorlack (he should be a destructive Armageddon Drake by now) and 2 Inferno/Fire drakes are enough.
* For the Elven marshal, 2 Blademasters, 1 Thrasher and 1 Arbiter.
* For the cat, 2 Drake Warriors and maybe a Sky Drake.
* For the mermaid, 1 Drake Warrior, the saurian heroes and Reshan.

This scenario has a special mechanic. If your drakes attack an enemy on a forest hex, they will ignite the hex and this fire will spread. Use this to your advantage.

When the Elven Lady dies, she will drop an artifact, the '''Sapphire of Ice'''. This will grant any unit with a ranged cold attack (which increments by level). The best unit to equip this is a Drake Warden/Drake Arbiter. Drake Enforcer/Drake Thrasher (but the extra attack just clutters the side bar UI so maybe not). Any other choice is good, but not as good as the Warden using it.

There is a lore book on the location of the cat "Princess Mew". You should really read it.

== Scenario 8: Overlook ==

The drakes have to escape through a cave. There are elves pursuing you (since you well...you know). Recruit some saurians to delay the elves and recall Fire Drakes and Drake Flares to navigate one of the tunnels. There is lore book inside the left tunnel. You will encounter undead inside these caves. Dispatch the Death Knight leader quickly and proceed onwards.

You will encounter an Ancient Lich who can recruit Liches and Spectres. However, if you attack him, you are prompted to form a truce or destroy him. The choice is up to you. However, forming a truce has a better benefit. He will open the escape route and delay the elves.

You have the chance to farm the level 3 elves for XP but it is a bit risky as there are Sylphs which can easily take out drakes and move relatively faster in caves. Retreat through the cave, remembering that Reshan should be the last unit to escape.

== Scenario 9: Ancestor ==

You start on a Keep/Encampment with the Saurian heroine units. You might have enough gold for 9 recalls (might be different by difficulty). The terrain is mostly snowy and swampy. There are monster units battling each other everywhere. Perfect farming spot.

=== Recall Priority: ===
* Hurricane/Sky Drakes: Best recallable option. Snowy Terrain? No problem. They will just fly over most terrain without any movement impediments at all.
* Drake Warriors: You can never go wrong with Drake Warriors.
* Fire Drakes. Two or more.
* Drake Flameheart: Only if you have a bunch of level 2 drakes recalled and can level up.
* One Saurian Soothsayer (to supplement Zedrix in healing). Optional.
* One Saurian Ambusher (she can level up fast here). Optional.

=== Ignore ===
* Drake Clasher caste recalls. It is a shame that the campaign's design does not encourage usage of clashers in most scenarios.
* Saurian Oracles. Most monsters are cold resistant, so might have these units sit this one out.

=== Monster Priority ===
* Yeti: Dangerous to confront without adequate support. 32 XP on kill so should be dealt with if encountered.
* Greater Icemonax: Probably has a masters degree in being the most annoying. resistant to most damage types. Avoid if able since you can get better kills here.
* Dread Bat: One Word. Annoying.
* Gryphon. Has a high chance of spawning next to your keep at start.
* Direwolf: perfect for XP farm.
* Cave Bear: good farm option

Your goal is get Gorlack to the beacon on top of the volcanic mountain range. Once there, you will meet a dragon and his wyrms. Then they will become your allies and finally, you have purge the map of all enemies.

== Scenario 10: Fire Meets Steel ==

You start at a new eerie establish on the volcanic mountain range. '''You can recruit level 2 drakes and saurians'''. At this point, your recruit list is now identical to the '''Age of Heroes''' Era's Drakes faction. Your enemies are dwarves.

In this scenario you have to resist the dwarven offensive for three days (18 turns). Here, recalling 2 Hurricane Drakes is obligatory for the swift victory tactics. Recall your loyal intendants and a Flameheart. Recruit Clashers and Burners, but prioritize on Drake Clasher recruitment. Losing a village deprives of +4 income so you should be focusing on retaining most of the villages.

Dwarven Thunderguards, Stalwarts and Berserkers should be approached with caution as they can gang up on your units. The dwarves also spawn from the mountain tunnels and the leader himself will be sending Gryphon Riders and Gryphon Masters This is where your Hurricane drakes come in. Send them to circumvent the enemy and collapse the tunnels. That way the subsequent waves will have less units to deal with. Keep the dwarves at bay by exploiting the mobility of the drakes and the lava reef.

At the end of the scenario, Reshan is returned to you.

== Scenario 11: Crosswind ==

The final scenario. Your enemy is the remnants of the Flight of Karron. The victory objective is surrounding Karron with 6 of your units. Additionally, the Saurian Flanker heroine (it's a she)...will turn on you. Oh, no! A spoiler! Deal with it.

The key to this scenario is Reshan himself.

Turn 1: Send Reshan south to the villages. When he captures them, he will spawn allies (veteran Nagas and Saurians, and swamp affinity monster units). There is another village near the mountain that does another spawn.
Likewise, recall another Hurricane Drake and send him to the village at the western/left edge of the map. The village spawns 1 troll, a giant spider and an greater icemonax.

Once Reshan has captured the 2 villages, rush all your spawned saurians, and monsters towards Karron. Reshan should be heading to Karron's keep and nullifying any chances of him recruiting. This is a bit tricky but doable.

=== Recall Priority ===
* Drake Blademasters. Probably the best units for this campaigns you can have. Recall all of them. Every single one.
* Drake Warden with Sapphire Orb.
* Saurian Oracles (as many as you got). Recruit if you lost all of them.
* A Drake Flameheart (to supplement the Oracles)
* Saurian Flankers

There are 2 lore tablets/secrets here (northeast and southeast of the starting keep).

Karron will spawn his Burner caste veterans and Glider caste veterans when he is attacked. Keep this in mind.

Once Reshan occupies the keep, Karron will not go for the keep, instead he will move to attacking to whatever he sees. This is a good moment to get him surrounded as your skirmishing flankers and swamp lizards are already there with nagas.

For the honorable way, just let Karron walk to his keep, while occupying the 5 adjacent hexes of the keep so when he moves, he will recruit just 1 unit and then on your turn, kill that unit and place your unit to capture him.

== Scenario 12: Epilogue ==
Cutscene Only Scenario.

[[Category: Campaigns - Walkthroughs]]
[[Category: Campaigns - Winds of Fate]]

Mainline Campaigns

2024-03-22T00:40:13Z

Name: Update the winds of fate campaign description.

{{Translations}}

These campaigns are included in the Wesnoth distribution. Most were written by fans of the game.
See [[ReferenceWML]] for information on how to make your own scenarios using the Wesnoth Markup Language. The following links are very likely to contain spoilers regarding the storyline.

== The Rise of Wesnoth ==
<div class="thumb tright">
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/The_Rise_Of_Wesnoth/images/campaign_image.png https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/The_Rise_Of_Wesnoth/images/campaign_image.png]
</div>

by [//www.wesnoth.org/forum/profile.php?mode=viewprofile&u=388 Shade]

Lead Prince Haldric through the distruction of the Green Isle and across the Ocean to establish the very kingdom of Wesnoth itself. The confrontation with Lich-Lord Jevyan awaits... (Hard level, 20 scenarios.)

* [[TheRiseOfWesnoth|Walkthrough]]
* [[TrowStoryLine|Story outline]], [[CharactersStorys#The_Rise_of_Wesnoth|Characters]], [[WesnothFigures#The_Rise_Of_Wesnoth|Biographies]], [[CampaignDialogue:TROW|Dialogue]]
* [//www.wesnoth.org/forum/viewtopic.php?f=22&t=10613 Discussion thread]
* [//units.wesnoth.org/trunk/mainline/en_US/The_Rise_of_Wesnoth.html Custom units]
* [[Geography_of_Wesnoth#The_Rise_of_Wesnoth|Geographical references]], [[Timeline_of_Wesnoth#5-2_BW|Position in timeline]]
<div style="clear:both"></div>

== Winds of Fate ==
<div class="thumb tright">
[https://github.com/wesnoth/wesnoth/blob/1.14/data/core/images/portraits/drakes/inferno.png https://raw.githubusercontent.com/wesnoth/wesnoth/1.14/data/core/images/portraits/drakes/inferno.png]
</div>
Note: added in version 1.17.0 of the game.

by Jonathan Kelly (name), SigurdFireDragon (based on the original by Fabi and ESR)

As the once plentiful hunting grounds of Morogor slip below the waves, war looms between drakes driven rogue by hunger and those still honorable. Yet the winds of fate may be shifting, for inspired by legends of vast far away lands, a pack of fledgling hunters makes ready to lead their kind on a journey towards salvation. (Hard level, 11 scenarios.)

* [[Winds of Fate|Winds of Fate Walkthrough]]
* [https://forums.wesnoth.org/viewtopic.php?t=49140 Discussion Thread]
<div style="clear:both"></div>

== An Orcish Incursion ==
Note: This campaign was removed in version 1.15.3 of the game.
<div class="thumb tright">
[https://raw.githubusercontent.com/wesnoth/wesnoth/1.14/data/campaigns/An_Orcish_Incursion/images/campaign_image.png https://raw.githubusercontent.com/wesnoth/wesnoth/1.14/data/campaigns/An_Orcish_Incursion/images/campaign_image.png]
</div>

by Josh Parsons; adapted for mainline by ESR.

Defend the forest of the elves against the first orcs to reach the Great Continent, learning valuable tactics as you do so. (Rookie level, 7 scenarios.)

* [[AnOrcishIncursion|Walkthrough]]
* [[An_Orcish_Incursion story|Story outline]], [[CharactersStorys#An_Orcish_Incursion|Characters]], [[CampaignDialogue:AOI|Dialogue]]
* [//www.wesnoth.org/forum/viewtopic.php?f=22&t=20249 Discussion thread]
* [[Geography_of_Wesnoth#An_Orcish_Incursion|Geographical references]], [[Timeline_of_Wesnoth#8_YW|Position in timeline]]
<div style="clear:both"></div>

== Legend of Wesmere ==
<div class="thumb tright">
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Legend_of_Wesmere/images/campaign_image.png https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/Legend_of_Wesmere/images/campaign_image.png]
</div>

by Santi; adapted for mainline by esr and fendrin

The tale of Kalenz, the High Lord who rallied his people after the second orcish invasion of the Great Continent and became the most renowned hero in the recorded history of the elves. (Hard level, 18 scenarios.)

* [[LegendofWesmere|Walkthrough]]
* [[LegendofWesmereStory|Story outline]], [[CharactersStorys#Legend_of_Wesmere|Characters]], [[WesnothFigures#Legend_of_Wesmere|Biographies]], [[CampaignDialogue:LOW|Dialogue]]
* [//forums.wesnoth.org/viewforum.php?f=51 Discussion threads]
*[[Geography_of_Wesnoth#The_Legend_of_Wesmere|Geographical references]], [[Timeline_of_Wesnoth#20_YW|Position in timeline]]
<div style="clear:both"></div>

== Secrets of the Ancients ==
<div class="thumb tright">
[https://github.com/wesnoth/wesnoth/blob/1.16/data/campaigns/Secrets_of_the_Ancients/images/portraits/campaign-image.png https://raw.githubusercontent.com/wesnoth/wesnoth/1.16/data/campaigns/Secrets_of_the_Ancients/images/portraits/campaign-image.png]
</div>

By [//forums.wesnoth.org/memberlist.php?mode=viewprofile&u=107794 beetlenaut]

Rediscover the secrets known by the lich lords of the Green Isle. They knew how to live forever, so why can't you?
(Hard level, 18 scenarios.)

*[[Secrets_of_the_Ancients_Walkthrough|Walkthrough]]
*[[CharactersStorys#Secrets_of_the_Ancients|Characters]], [[WesnothFigures#Secrets_of_the_Ancients|Biographies]], [[CampaignDialogue:SOTA|Dialogue]]
*[//forums.wesnoth.org/viewtopic.php?f=8&t=40545 Discussion Thread], [//forums.wesnoth.org/viewtopic.php?f=31&t=43116 Feedback Thread]
*[//units.wesnoth.org/trunk/mainline/en_US/Secrets%20of%20the%20Ancients.html Custom units]
*[[Geography_of_Wesnoth#Secrets_of_the_Ancients|Geographical references]], [[Timeline_of_Wesnoth#22-23_YW|Position in timeline]]
<div style="clear:both"></div>

== The Sceptre of Fire ==
<div class="thumb tright">
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Sceptre_of_Fire/images/campaign_image.png https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/Sceptre_of_Fire/images/campaign_image.png]
</div>

by turin

''The mark of Wesnoth's banner bold''

''Comes not from its own land;''

''It comes from Dwarfdom, grim and old''

''Made by a runesmith's hand.''

''So now I tell from whence it came -''

''The Fire-sceptre great -''

''And of the makers of the same,''

''Their tale I now relate...'' (Hard level, 10 scenarios)

* [[Sceptre of Fire|Walkthrough]]
* [[Sceptre of Fire story|Story outline]], [[CharactersStorys#Sceptre_of_Fire|Characters]], [[CampaignDialogue:SOF|Dialogue]]
* [//www.wesnoth.org/forum/viewtopic.php?f=22&t=20255 Discussion thread]
* [//units.wesnoth.org/trunk/mainline/en_US/Sceptre_of_Fire.html Custom units]
* [[Geography_of_Wesnoth#Scepter_of_Fire|Geographical references]], [[Timeline_of_Wesnoth#25-40_YW|Position in timeline]]
<div style="clear:both"></div>

== A Tale of Two Brothers ==
<div class="thumb tright">
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Two_Brothers/images/campaign_image.png https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/Two_Brothers/images/campaign_image.png]
</div>

* by [//www.wesnoth.org/forum/profile.php?mode=viewprofile&u=93 Circon]

An evil mage is threatening the small village of Maghre and its inhabitants. The village's mage sends to his warrior brother for help, but not all goes as planned. Can you help? (Novice level, 4 scenarios.)

* [[ATaleOfTwoBrothers|Walkthrough]]
* [[A Tale Of Two Brothers Story|Story outline]], [[CharactersStorys#A_Tale_Of_Two_Brothers|Characters]], [[CampaignDialogue:TB1.9|Dialogue]]
* [//www.wesnoth.org/forum/viewtopic.php?f=22&t=10339 Discussion thread]
* [[Geography_of_Wesnoth#A_Tale_of_Two_Brothers|Geographical references]], [[Timeline_of_Wesnoth#363_YW|Position in timeline]]
<div style="clear:both"></div>

== Descent into Darkness ==
<div class="thumb tright">
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Descent_Into_Darkness/images/campaign_image.png https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/Descent_Into_Darkness/images/campaign_image.png]
</div>

by esci

The northern frontier town of Parthyn is annually raided by neighbouring tribes of orcs. Malin Keshar, an outcast mage, seeks to defend his home and wreak vengeance on the orcs by any means necessary, even if it means sacrificing his own soul in the process. (Intermediate level, 10 scenarios.)

* [[DescentIntoDarkness|Walkthrough]]
* [[Descent Into Darkness story|Story outline]], [[CharactersStorys#Descent_into_Darkness|Characters]], [[CampaignDialogue:DID|Dialogue]]
* [//www.wesnoth.org/forum/viewtopic.php?f=22&t=20251 Discussion thread]
* [//units.wesnoth.org/trunk/mainline/en_US/Descent_into_Darkness.html Custom units]
* [[Geography_of_Wesnoth#Descent_Into_Darkness|Geographical references]], [[Timeline_of_Wesnoth#389_YW|Position in timeline]]
<div style="clear:both"></div>

== Delfador's Memoirs ==

<div class="thumb tright">
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Delfadors_Memoirs/images/campaign_image.png https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/Delfadors_Memoirs/images/campaign_image.png]
</div>

Wesnoth seems to be slipping inexorably into chaos, as marauding orcs pour south across the Great River, and mysterious and deadly creatures roam the night. Who is the shadowy Iliah-Malal? Can you defeat him before he destroys all life in Wesnoth? (Intermediate level, 19 scenarios.)

* [[DelfadorsMemoirs|Walkthrough]]
* [[DelfadorsMemoirsStory|Story outline]], [[CharactersStorys#Delfador.27s_Memoirs|Characters]], [[CampaignDialogue:DM|Dialogue]]
* [//www.wesnoth.org/forum/viewtopic.php?f=22&t=25554 Discussion thread]
* [//units.wesnoth.org/trunk/mainline/en_US/Delfadors_Memoirs.html Custom units]
* [[Geography_of_Wesnoth#Delfador.27s_Memoirs|Geographical references]], [[Timeline_of_Wesnoth#468_YW|Position in timeline]]
<div style="clear:both"></div>

== Liberty ==
<div class="thumb tright">
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Liberty/images/campaign_image.png https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/Liberty/images/campaign_image.png]
</div>

by scott

As the shadow of civil war deepens across Wesnoth, a band of hardy marchlanders revolts against the governance of the new queen. To win their way to freedom, they must learn to use shadows and deception to rout the trained blades of the Wesnothian army. (Novice level, 7 scenarios.)

* [[Liberty|Walkthrough]]
* [[Liberty story|Story outline]], [[CharactersStorys#Liberty|Characters]], [[CampaignDialogue:L|Dialogue]]
* [//www.wesnoth.org/forum/viewtopic.php?f=22&t=20252 Discussion thread]
* [//units.wesnoth.org/trunk/mainline/en_US/Liberty.html Custom units]
* [[Geography_of_Wesnoth#Liberty|Geographical references]], [[Timeline_of_Wesnoth#501_YW|Position in timeline]]
<div style="clear:both"></div>

== Heir to the Throne ==

<div class="thumb tright">
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Heir_To_The_Throne/images/campaign_image.png https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/Heir_To_The_Throne/images/campaign_image.png]
</div>

by [//www.wesnoth.org/forum/profile.php?mode=viewprofile&u=3 Dave]

Fight to regain the throne of Wesnoth, of which you are the legitimate heir. (Novice level, 23 scenarios.)

* [[HeirToTheThrone|Walkthrough]]
* [[HtttStoryLine|Story outline]], [[CharactersStorys#Heir_to_the_Throne|Characters]], [[WesnothFigures#Heir_to_the_Throne|Biographies]], [[CampaignDialogue:HttT|Dialogue]]
* [//www.wesnoth.org/forum/viewtopic.php?f=22&t=10322 Discussion thread]
* [//units.wesnoth.org/trunk/mainline/en_US/Heir_To_The_Throne.html Custom units]
* [[Geography_of_Wesnoth#Heir_To_The_Throne|Geographical references]], [[Timeline_of_Wesnoth#517_YW|Position in timeline]]
<div style="clear:both"></div>

== Northern Rebirth ==
<div class="thumb tright">
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Northern_Rebirth/images/campaign_image.png https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/Northern_Rebirth/images/campaign_image.png]
</div>

by [//www.wesnoth.org/forum/profile.php?mode=viewprofile&u=100782 Taurus]

For the people of Dwarven Doors the choice was stark: either drudge as downtrodden slaves for the orcs until the end of their brief and miserable lives, or risk all for freedom and rise against their cruel overlords. Little did they suspect that their struggle would be the hinge of great events that might restore the Northlands to the glory they had once known. (Expert level, 13 scenarios.)

* [[Northern Rebirth|Walkthrough]]
* [[Northern Rebirth story|Story outline]] , [[CharactersStorys#Northern_Rebirth|Characters]], [[CampaignDialogue:NR|Dialogue]]
* [//www.wesnoth.org/forum/viewtopic.php?f=22&t=20253 Discussion thread]
* [//units.wesnoth.org/trunk/mainline/en_US/Northern_Rebirth.html Custom units]
* [[Geography_of_Wesnoth#Northern_Rebirth|Geographical references]], [[Timeline_of_Wesnoth#534_YW|Position in timeline]]
<div style="clear:both"></div>

== The Hammer of Thursagan ==
<div class="thumb tright">
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/The_Hammer_of_Thursagan/images/campaign_image.png https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/The_Hammer_of_Thursagan/images/campaign_image.png]
</div>

by ESR (Eric S. Raymond)

In the first years of the Northern Alliance, an expedition from Knalga seeks out their kin at Kal Kartha and to learn the fate of the legendary Hammer of Thursagan. The perils of their journey through the wild Northern Lands, though great, pale beside the evil they will face at its end. (Intermediate level, 8 scenarios.)

* [[TheHammerOfThursagan|Walkthrough]]
* [[TheHammerOfThursagan story|Story outline]], [[CharactersStorys#The_Hammer_of_Thursagan|Characters]], [[WesnothFigures#The_Hammer_Of_Thursagan|Biographies]], [[CampaignDialogue:THOT|Dialogue]]
* [//www.wesnoth.org/forum/viewtopic.php?f=22&t=20258 Discussion thread]
* [//units.wesnoth.org/trunk/mainline/en_US/The_Hammer_of_Thursagan.html Custom units]
* [[Geography_of_Wesnoth#The_Hammer_of_Thursagan|Geographical references]], [[Timeline_of_Wesnoth#550_YW|Position in timeline]]
<div style="clear:both"></div>

== The South Guard ==
<div class="thumb tright">
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/The_South_Guard/images/campaign_image.png https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/The_South_Guard/images/campaign_image.png]
</div>

* by [//www.wesnoth.org/forum/profile.php?mode=viewprofile&u=872 aelius]

A young Knight, Deoran is dispatched to the southern Wesnoth province of Kerlath to investigate the ravaged towns at the border. Thrust quickly into a hapless conflict against marauding bandits, Deoran must rally the remaining men of the derelict South Guard to defend his country. (Novice level, 8 scenarios.)

* [[TheSouthGuard|Walkthrough]]
* [[South Guard story|Story outline]], [[CharactersStorys#The_South_Guard|Characters]], [[CampaignDialogue:TSG|Dialogue]]
* [//www.wesnoth.org/forum/viewtopic.php?f=22&t=10323 Discussion thread]
* [//units.wesnoth.org/trunk/mainline/en_US/The_South_Guard.html Custom units]
* [[Geography_of_Wesnoth#The_South_Guard|Geographical references]], [[Timeline_of_Wesnoth#607_YW|Position in timeline]]
<div style="clear:both"></div>

== Eastern Invasion ==
<div class="thumb tright">
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Eastern_Invasion/images/campaign_image.png https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/Eastern_Invasion/images/campaign_image.png]
</div>

by [//www.wesnoth.org/forum/profile.php?mode=viewprofile&u=176 Turin]

There are rumours of undead attacks on the eastern border of Wesnoth. You, an officer in the Royal Army, have been sent to the eastern front to protect the villagers and find out what is happening. (Intermediate level, 16 scenarios.)

* [[TheEasternInvasion|Walkthrough]]
* [[EiStoryLine|Story outline]], [[CharactersStorys#Eastern_Invasion|Characters]], [[CampaignDialogue:EI|Dialogue]]
* [//www.wesnoth.org/forum/viewtopic.php?f=22&t=10325 Discussion thread]
* [//units.wesnoth.org/trunk/mainline/en_US/Eastern_Invasion.html Custom units]
* [[Geography_of_Wesnoth#Eastern_Invasion|Geographical references]], [[Timeline_of_Wesnoth#625_YW|Position in timeline]]
<div style="clear:both"></div>

== Dead Water ==

<div class="thumb tright">
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Dead_Water/images/campaign_image.png https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/Dead_Water/images/campaign_image.png]
</div>

By [//forums.wesnoth.org/memberlist.php?mode=viewprofile&u=107794 beetlenaut]

You are Kai Krellis, son and heir of the last merman king but only a child. A necromancer is turning your subjects into undead slaves! Lead your people on a mission to convince a powerful mer-sorceress to help you repel the invasion. The oceans near the Northern Lands are perilous, so you will need cunning and bravery to survive. But first you need to gain the respect of your troops!
(Intermediate Level, 10 scenarios.)

*[[Dead_Water|Walkthrough]]
*[[CharactersStorys#Dead_Water|Characters]], [[WesnothFigures#Dead_Water|Biographies]], [[CampaignDialogue:DW|Dialogue]]
*[//forums.wesnoth.org/viewtopic.php?f=45&t=31304 Discussion Thread]
*[//units.wesnoth.org/trunk/mainline/en_US/Dead_Water.html Custom units]
*[[Geography_of_Wesnoth#Dead_Water|Geographical references]], [[Timeline_of_Wesnoth#626_YW|Position in timeline]]
<div style="clear:both"></div>

== Son of the Black-Eye ==
<div class="thumb tright">
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Son_Of_The_Black_Eye/images/campaign_image.png https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/Son_Of_The_Black_Eye/images/campaign_image.png]
</div>

started by Benj, completed by Taurus

Your father Karun Black-Eye was the greatest orcish leader that ever lived. Now, as his son, it's up to you to thwart the selfish designs of the humans who have broken the old agreements with the orcs and are bent upon taking your lands. Unite the warring orcish tribes, bring together the Orcish Council and call up the Great Horde to send the human-worms and their wose-born allies to the Land of the Dead! (Expert level, 18 scenarios.)

* [[SonOfThe_BlackEye|Walkthrough]]
* [[Black Eye story|Story outline]], [[CharactersStorys#Son_of_the_Black_Eye|Characters]], [[WesnothFigures#Son_Of_The_Black_Eye|Biographies]], [[CampaignDialogue:SOTBE|Dialogue]]
* [//www.wesnoth.org/forum/viewtopic.php?f=22&t=20257 Discussion thread]
* [//units.wesnoth.org/trunk/mainline/en_US/Son_of_the_Black-Eye.html Custom units]
* [[Geography_of_Wesnoth#Son_Of_The_Black_Eye|Geographical references]], [[Timeline_of_Wesnoth#842_YW|Position in timeline]]
<div style="clear:both"></div>

== Under the Burning Suns ==
<div class="thumb tright">
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Under_the_Burning_Suns/images/campaign_image.png https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/Under_the_Burning_Suns/images/campaign_image.png]
</div>

by [//www.wesnoth.org/forum/profile.php?mode=viewprofile&u=149 quartex]

In the distant future a small band of elves struggles to survive amidst the ruins of fallen empires. Lead your people out of the desert on an epic journey to find a new home. (Expert level, 10 scenarios.)

* [[UnderTheBurningSuns|Walkthrough]]
* [[UtBSStoryLine|Story outline]], [[CharactersStorys#Under_the_Burning_Sun|Characters]], [[CampaignDialogue:UTBS|Dialogue]]
* [//www.wesnoth.org/forum/viewtopic.php?f=22&t=10491 Discussion thread]
* [//units.wesnoth.org/trunk/mainline/en_US/Under_the_Burning_Suns.html Custom units]
* [[Geography_of_Wesnoth#Under_The_Burning_Suns|Geographical references]], [[Timeline_of_Wesnoth#After_the_Fall|Position in timeline]]
<div style="clear:both"></div>

== See also ==
* [[Guide_to_UMC_Campaigns]]

[[Category:Review on Release]]
[[Category:Campaigns|*]]
[[Category:World_of_Wesnoth]]

Timeline of Wesnoth

2024-02-10T13:43:57Z

Name: Make race names consistently lowercase.

{{Translations}}
This is a chronological history of the country of Wesnoth and surrounding regions, gleaned from written accounts and verbal histories passed down through the generations. Portions of entries surrounded by parentheses and containing a question mark are assumed or unconfirmed information. The history is sorted by era, and within the era by date, using the Foundation of Wesnoth as a base. BW=Before Wesnoth, YW=Years Wesnoth. They function the same way as BC and AD do in our timekeeping system. Each of the eras is summarized before the timeline for that era begins. This history of the Great Continent is a subject of active scholarship.

The world that Wesnoth resides in is called Irdya. Before the Great Fall and the (unchronicled) technological age, this name is only rarely used.

'''Spoiler warning!'''
This page contains plot spoilers to several campaigns.

__NOTOC__
[[#Prehistory - 20 YW: The Founding of Wesnoth|The Founding of Wesnoth]]

[[#20-130 YW: The Taming of the Wild|The Taming of the Wild]]

[[#200-350 YW: The Golden Age of Wesnoth|The Golden Age of Wesnoth]]

[[#350-417 YW: The First Dark Age of Wesnoth|The First Dark Age of Wesnoth]]

[[#417-530 YW: The Turmoil of Asheviere|The Turmoil of Asheviere]]

[[#530-630 YW: The Age of Fear|The Age of Fear]]

[[#628-673 YW: The Silver Age of Wesnoth|The Silver Age of Wesnoth]]

[[#761-816 YW: The Legacy of Black-Eye Karun|The Legacy of Black-Eye Karun]]

[[#After the Great Fall|After the Great Fall]]

== Prehistory - 20 YW: The Founding of Wesnoth ==
During the age of the Founding of Wesnoth, there were two important geographic locations, these being the Green Isle and the Great Continent. Haldric is the main historical figure at this time. This age ends with the founding of Wesnoth as a country in the Great Continent, and with orcs attacking both elves and men from the sea.

=== Prehistory ===
* Elves and dwarves inhabit the Great Continent.
* Humans inhabit the distant West.
* Haldric's people colonise the [[Geography_of_Wesnoth#The_Green_Isle|Green Isle]] from a continent further to the west.

=== 200 BW ===
* The Lich-Lords arrive on the Green Isle after losing a war in the distant West.
* After a long war Haldric's people come to dominate the Green Isle.
* The 'Wesfolk' and their Lich-Lords are pushed onto marginal lands.

=== 12 BW ===
* The Crown Prince of Southbay discovers the Great Continent.

=== 11-7 BW ===
* The Crown Prince makes several voyages between the Green Isle and the Great Continent.

=== 6 BW ===
* Following these voyages to the Great Continent, the elder Crown Prince falls ill and dies.
* His younger brother is implicated in a plot to kill him.
* As a distraction the younger Prince starts a war with the Wesfolk and their Lich-Lords.
* The Lich-Lords sense they will be destroyed and open gates to the homeland of the orcs in the West.

=== 5-2 BW ===
* The Green Isle is overrun with orcs.
* The Wesfolk desert their Lich-Lords as they fear becoming prey for the orcs.
* [[CharactersStorys#Prince_Haldric|Prince Haldric]] leads the evacuation of the survivors to the Great Continent. [[Mainline_Campaigns#The_Rise_of_Wesnoth|'''The Rise of Wesnoth''']] begins.

=== 1 BW ===
* Human settlers, led by Prince Haldric, arrive at the western coast of the Great Continent (the landfall occurs in the future Bay of Pearls) in large numbers.
* Humans arrive in the middle of a simmering dispute between the elves and dwarves.
* The elves and dwarves are distrustful of humans, and there is a small skirmish.
* Messengers from Wesmere Forest come and ask Haldric to come before the Ka'lian.
* Prince Haldric asks the Four elvish Lords ([[CharactersStorys#Lady_Dionli|Dionli]], [[CharactersStorys#Lord_Logalmier|Logalmier]], [[Aryad]], and [[El'Isomithir]]) for help and land.
* They set before him four quests to prove his worth, which he completes.

=== 1 YW ===
* [[CharactersStorys#Prince_Haldric|Haldric]] is granted the plains north and south of the Great River.
* Haldric agrees to a Pact of Mutual Defence with the elves, but the Ka'lian decides it will betray him and allow humans and orcs to exhaust each other in war if the opportunity presents. Haldric, learning of this, considers the Pact a dead letter.
* The Ruby of Fire is temporarily hidden, and the [[CharactersStorys#Lich-Lord_Jevyan|lich-lord Jevyan]] is deceived into believing it is held by the elves.
* Haldric founds the country of [[Geography_of_Wesnoth#Wesnoth|Wesnoth]] in the central plain south of the great River.
* Reign of Haldric I (formerly prince Haldric) begins. [[Mainline_Campaigns#The_Rise_of_Wesnoth|'''The Rise of Wesnoth''']] ends.

=== 2 YW ===
* Orcs, following the ships fleeing from the Green Isle, begin to arrive on the Great Continent.
* These orcs are defeated by Haldric's forces.
* Some of the orcish survivors flee back to the Green Isle, others move to attack the elves.
* King Haldric helps the elves fight the surviving orcs.

=== 8 YW ===
* A second wave of orcs arrive from the Green Isle; these orcs begin claiming large portions of the northern Great Continent for themselves.
* [[CharactersStorys#Erlornas|Erlornas]] of Wesmere is involved in the first direct elvish clash with orcs ([[Mainline_Campaigns#An_Orcish_Incursion|'''An Orcish Incursion''']] takes place in 8-9YW).
* Haldric I publicly repudiates the Pact he spoke with the elves, refusing to give aid.

=== 9-11 YW ===
* Many elves are killed in battle by the orcs.
* Elvish emissaries are turned away from Wesnoth.

=== 12 YW ===
* Orcs fail to take the Wesmere Forest and instead march down the coast, devastating human settlements there.
* Elves refuse to aid the humans in confronting the orcs.
* Human refugees from the coastal settlements relocate in what will become known as the Great Central Plain. Dan'Tonk, which will become Wesnoth's largest city, is founded.

=== 20 YW ===
* [[CharactersStorys#Prince_Haldric|Haldric I]] dies.
* [[CharactersStorys#Haldric_II|Haldric II]] ascends to the throne.
* [[CharactersStorys#Kalenz_2|Kalenz]] and [[CharactersStorys#Landar|Landar]] escape an orcish invasion of their home in Lintanir Forest. [[Mainline_Campaigns#Legend_of_Wesmere|'''The Legend of Wesmere''']] begins.
* Humans and elves decisively defeat the orcs at Tath, thus halting the orcish advance.
* A new treaty between humans and elves is signed and King Haldric II allows emissaries of the elves to return to Wesnoth.
* Elves inform [[CharactersStorys#Haldric_II|Haldric II]] of the danger posed by the unshielded Ruby of Fire.
* [[CharactersStorys#Kalenz_2|Kalenz]] and [[CharactersStorys#Landar|Landar]], later to become successive High Lords of the Elves, are able to sneak into an orcish camp by stealth and assassinate the Great Chief Brurbar. A long orcish civil war for succession follows. The orcs are unable to undertake action against any other race during this period and Wesnoth enjoys a long period during which it can expand with little opposition.

== 20-130 YW: The Taming of the Wild ==
This era is that in which the kingdom of [[Geography_of_Wesnoth#Wesnoth|Wesnoth]] expanded and defined its borders, and settled the area which it had claimed for its own. The Taming of the Wild refers to the settling of the unsettled lands, as well as to the colonization of the Northlands. The end of this era is marked by friction between the city-state of [[Geography_of_Wesnoth#Elensefar|Elensefar]] and the country of Wesnoth, which will continue for the next several hundred years.

=== 21 YW ===
* Founding of the Great Academy on Alduin.

* [[CharactersStorys#Kalenz|Kalenz]] is relieved of command by the Ka'lian. He retires to Lintanir Forest with [[CharactersStorys#Cleodil|Cleodil]]. A faction of xenophobic elves begins to gather around [[CharactersStorys#Landar|Landar]].

=== 22 YW ===
* While studying at the Academy, [[CharactersStorys#Ardonna_.2F_Ardryn-Na|Ardonna]] resolves to spend the winter researching the Lich Lords' longevity.

=== 23 YW ===
* Action of '''Secrets of the Ancients''' takes place.

=== 25-40 YW ===
* In 25 YW [[CharactersStorys#Haldric_II|Haldric II]] sends an expedition to retrieve the Ruby of Fire from its place of concealment.
* Haldric II commissions a dwarven tribe to build the Sceptre of Fire with the Ruby of Fire as its centerpiece; elves associated with [[CharactersStorys#Landar|Landar's]] faction attack during the transfer. [[Mainline_Campaigns#The_Sceptre_of_Fire|'''Sceptre of Fire''']] begins.
* Action of '''The Sceptre of Fire''' takes place. Haldric II is informed that the Sceptre was both completed and lost in the year 40. It will not be recovered for nearly 500 years.
* With the death of [[CharactersStorys#Thursagan|Thursagan]], the Runemaster, all runemasters are killed and runesmithing is lost for several centuries.

=== 26-50 YW ===
* [[CharactersStorys#Landar|Landar]] declares himself High Lord of the Elves, leading to civil war.

=== 51 YW ===
* Wesnothian New Writing (the script later called "steel-hand", to distinguish it from the more complex "brush-hand" cursive brought from the [[Geography_of_Wesnoth#The_Green_Isle|Green Isle]]) is promulgated by royal decree. From this date all royal documents and public inscriptions are in New Writing. It spreads rapidly via the mercantile class. The older brush-hand writing continues to be used for magical purposes, scholarship, and in certain elevated literary forms.

=== 50-93 YW ===
* Elvish civil war (and [[Mainline_Campaigns#Legend_of_Wesmere|'''The Legend of Wesmere''']]) ends. [[CharactersStorys#Kalenz_2|Kalenz]] declared High Lord, begins reorganizing and militarizing elvish society to fight the orcs. In late 93 YW he cedes control to a reconstituted Ka'lian and retires again to the Forest of Lintanir.

=== 161-164 YW ===
* The newly crowned king sought to make safe once and for all the wildlands that separated the human cities surrounding Weldyn and the coastal regions of [[Elensefar]].
* The grand army of Wesnoth, personally led by the High Council of Archmagi, destroyed all enemies residing within Wesnoth.
* The city-state of Elensefar is formally united to the kingdom. Settlements from it spread north of the river into the new frontier province of Annuvin, carefully avoiding the margins of Wesmere Forest.

=== 164-176 YW ===
* During this twelve year span, the western fortress of Halstead was erected in the very heart of the western wilderlands.

=== 199 YW ===
* Emboldened by the far-reaching arm of Halstead's protection, settlement in the west explodes
* The settlements of Aldril and Carcyn grow to become major cities, the first as an important port due to its position on the Bay of Pearls, and the second as a stop on the road to Elensefar and military outpost along the Great River
* Settlers from Carcyn cross the Great River to establish the first settlements north of it and east of Wesmere.

== 200-350 YW: The Golden Age of Wesnoth ==
The Golden Age of Wesnoth was the time of the great kings, and of peace and prosperity within the kingdom. The orcs had suffered a grave defeat at the hands of Wesnoth and Elensefar seventy-five years earlier, so they did not pose much of a threat, and whenever they did attack they were quickly defeated. This allowed the army to lessen in size, and the kings of this age to undertake the great public works they are renowned for. The era ends when the king of Wesnoth dies without an heir, and a new dynasty begins.

=== 251 YW ===
* [[CharactersStorys#Cleodil|Cleodil]], wife of [[CharactersStorys#Kalenz_2|Kalenz]], dies.

=== 350 YW ===
* Disintegration of the Kingdom follows the death of Haldric IV.
* [[Geography_of_Wesnoth#Elensefar|Elensefar]] remains a province of Wesnoth but exerts increasing independence due to isolation.
* Treaty between lord of Elensefar and king of Wesnoth signed.

== 350-417 YW: The First Dark Age of Wesnoth ==
The first Dark Age was a time of strife and invasion. When Haldric IV died, he left Wesnoth without a king, and the next 70 years were marked by short-lived dynasties, attacks by ever more aggressive orcs, and the further separation of Wesnoth and Elensefar. The Dark Age ended when Garard I took the throne, and began a new dynasty that would last for several hundred years.

=== 360 YW ===
* [[CharactersStorys#Malin_Keshar|Malin Keshar]] born in Parthyn.

=== 363 YW ===
* Last of [[CharactersStorys#Kalenz|Kalenz's]] children dies. Kalenz, condemned to outlive his offspring by the potion of Crelanu, leaves the Forest of Lintanir and begins wandering the Great Continent.

* Village of Maghre terrorized by a minor necromancer. Action of [[Mainline_Campaigns#A_Tale_Of_Two_Brothers|'''A Tale of Two Brothers''']] takes place.

=== 389 YW ===
* Garard, a future king of Wesnoth, is born.
* [[CharactersStorys#Malin_Keshar|Malin Keshar]] returns to Parthyn from the Academy at Alduin. [[Mainline_Campaigns#Descent_into_Darkness|'''Descent Into Darkness''']] begins.

== 417-530 YW: The Turmoil of Asheviere ==
King Garard's dynasty was long-lived and productive, but it was also punctuated by significant turmoil: the end of the first king's reign was marred by orcish and undead raids, and the second was murdered by his own wife and son. It was not until 517 YW that the usurpation of the throne by Queen Mother Asheviere was ended.

=== 417 YW ===
* Ending years of strife and division, Garard I seizes the throne and becomes king of Wesnoth, beginning the [[Garardine Dynasty]].

=== 440 YW ===
* [[CharactersStorys#Garard_II|Crown Prince Garard II]] is born.

=== 442 YW ===
* [[CharactersStorys#Delfador|Delfador]], later called "the Great", is born.

=== 450 YW ===
* Prince Arand is born.

=== 468 YW ===
* Zorlan becomes Great Chief of the northern orcs
* [[CharactersStorys#Delfador|Delfador]] graduates from the Great Academy. [[Mainline_Campaigns#Delfador.27s_Memoirs|'''Delfador's Memoirs''']] begins.

=== 470 YW ===
* Garard I dies; [[CharactersStorys#Garard_II|Garard II]] ascends to the throne of Wesnoth
* Orcs under Great Chief Zorlan and undead raised by the necromancer [[CharactersStorys#Iliah-Malal|Iliah-Malal]] raid Wesnoth's borders. All but the first and the last three scenarios of [[Mainline_Campaigns#Delfador.27s_Memoirs|'''Delfador's Memoirs''']] take place in this year.
* Control of the Estmarks is effectively lost during this war, not to be regained for decades. Outposts are built on the near side of the Weldyn to repel orc raids. The long watch of the River Guard begins.

=== 478 YW ===
* Garard II marries Asheviere.
* Garard issues the Edict of the Sceptre, providing that the crown shall settle after his death on whichever member of the royal family successfully retrieves it from the Caverns of Flame.

=== 480 YW ===
* Crown Prince Eldred is born.

=== 483 YW ===
* Erain and Ethyn, identical twins and brothers of Eldred, are born.

=== 498 YW ===
* Princess Li'sar is born.

=== 500 YW ===
* Prince Konrad is born, the youngest of several sons of Prince Arand.
* Wesnoth and the orcs of the north go to war.

=== 501 YW ===

===== Betrayal on the battlefield =====
* Garard leads his army to orc encampment at Galcadar by the Ford of Abez.
* Garard's forces split into two groups, one led by himself and the other by his son Eldred.
* Eldred betrays his father and attacks him with the troops under his control.
* Eldred slays King Garard and his uncle Prince Arand on the battlefield of Abez.

===== Reprisal =====
* Delfador escapes the battle and heads to Weldyn.
* Eldred gives tribute to the orcish king, who stops his attacks.
* Delfador gathers a force of Loyalists to avenge Garard's Death.
* Eldred's forces confront Delfador's Loyalists at Weldyn.
* The Loyalists are defeated, but Eldred is slain by Delfador in the fight.

===== Asheviere seizes power =====
* Asheviere orders the slaughter of Garard's nephews and declares herself Queen of Wesnoth.
* Hearing of the news Delfador infiltrates the palace.
* Delfador finds the youngest prince Konrad as he is slain.
* Delfador flees, taking Konrad's body for burial to the land of the elves.
* While traveling through Wesnoth, Elf Lady Parandra finds an orphaned human child.
* Parandra and Delfador agree to give the orphan the identity of Prince Konrad.
* Delfador and Konrad flee to live in refuge with the Wood Elves of the great southwestern forest.

===== The country resists Asheviere =====
* Elensefar refuses to submit to Asheviere and declares itself an independent city-state.
* After several defeats, Wesnoth's army retreats from the remote areas of the kingdom. The western Wesnothian border recedes, is fixed, and remains heavily defended.
* As a result of the loyalist withdrawal, several small human communities on the west coast of the Great Continent live in relative independence while elves flourish in the great forest to the southwest of Wesnoth.
* A band of Wesnoth citizens organizes resistance to Asheviere's siezure of power. They are eventually forced to abandon their home and settle in the Three Sisters ('''Liberty''').

=== 502-517 YW ===
* Delfador raises Konrad under the protection of the elves.

=== 517 YW ===
* Asheviere hires orcish forces to hunt down her nephew-in-law Konrad.
* Orcish forces converge on Delfador's refuge.
* Konrad flees his home with the elves and embark upon a quest to regain the throne of Wesnoth. '''Heir To The Throne''' begins.

=== 518 YW ===
* Konrad crosses the Great River into the Northlands on a search for the Sceptre of Fire.
* They enter the Caves of Knalga, allied with Princess Li'sar, and find it.
* They return to Wesnoth and claim the throne. '''Heir to the Throne''' ends.

=== 522 YW ===
* Birth of Princess Ana'sar.

=== 530 YW ===
* Wesnothian colonists begin reclaiming the Estmarks.

=== 544 YW ===
* With both sides of the lower Weldyn River again civilized territory, the River Guard posts south of Soradoc are abandoned. Wesnothian military activity shifts eastward into the Estmarks.

== 530-630 YW: The Age of Fear ==
The Age of Fear takes its names from the events of the end of the era. On the surface, the first 77 years were very uneventful for the kingdom of Wesnoth. However, during this time unexplainable magical events took place, especially in the eastern lands. Previously tamed lands were slowly claimed by wilderness as fear and paranoia gradually overshadowed the spirit of pioneering and adventure displayed earlier in Wesnoth's history. In the last 10 years of the age, Wesnoth bore the brunt of the most powerful undead attack ever and was nearly destroyed. By the end of the era, most of Wesnoth had been made barren, most of the great buildings inside and outside of Weldyn were razed, and the population of Wesnoth was half of what it had been.

It was in this era that certain areas of the chaotic Northlands were for the first time put into any kind of law and order. A small group of humans and dwarves, accepting anyone of any race who wished to join, formed themselves into the "Northern Alliance”, with the vision of making the Northlands safe to live in. Over time, this alliance grew slowly but steadily in power. By the end of the era, the alliance had succeeded in making a few small areas, including Knalga and the surrounding regions, stable and prosperous. Consequently, many people evacuated from the wasteland that most of Wesnoth had become and moved north - depleting the population of Wesnoth still further.

=== 533 YW ===
* Delfador succumbs to old age and dies, his body is entombed alongside his staff in Eregonor.
* The next great sage of Wesnoth, [[CharactersStorys#Dacyn|Dacyn]], is born.

=== 534 YW ===

* The small community of Dwarven Doors, in the Northlands just outside Knalga, rebels against the orcish overlords. '''Northern Rebirth''' begins.
* The residents, led by Tallin, head underground and find dwarves, whom they ally with.
* Their combined forces destroy a lich who is attempting to claim Knalga as his own.
* Abhai finds the [[CampaignDialogue:NR#Abhai_Finds_Rod_of_Justice|Rod of Justice]].

=== 535 YW ===

* The warlord-aspirant Rakshas attacks Tallin and his forces, but does not penetrate the dwarves' defences.
* To help defeat the orcs, Tallin secures the help of two Liches, and rescues an elvish princess to secure the help of the elves.
* Assisted by his new allies, Tallin smashes the forces of Rakshas.
* According to some historians, Tallin and the elvish princess are married; others say they parted in bad blood.
* To preserve the new-found peace in the Northlands, Tallin and his allies form the Northern Alliance. '''Northern Rebirth''' ends.

=== 550 YW ===

* Lord Hamel of Knalga sends an expedition to Kal Kartha to determine the fate of the Hammer of Thursagan ('''The Hammer of Thursagan''' takes place in late 550 YW to early 551 YW.).
* Dwarves at Knalga and elsewhere begin to reclaim the lost art of runesmithing.
* Wesnothian colonization expands southward past Fort Tahn.

=== 563 YW ===
* Konrad and Li'sar die after an extraordinarily long reign.
* Princess Ana'sar becomes queen.
* The seer Galdren becomes prominent at the court of Weldyn.

=== 585 YW ===
* Queen Ana'sar retires.
* Haldric VII becomes king of Wesnoth.

=== 589 YW ===
* Dacyn the White Mage and Ravanal, an eastern wizard, compete to be the king's advisor.
* The seer Galdren dies after advising Haldric VII to choose Dacyn.
* The king does as Galdren advises.

=== 593 YW ===
* Ravanal reveals that he has turned to evil, and flees from Weldyn.
* Konrad II is born.
* Certain southern frontier regions are formally annexed to the Kingdom of Wesnoth as the Province of Kerlath.

=== 598 YW ===
* South Guard organized as a semi-detached formation of the Royal Army, to protect the inhabitants of the frontier province of Kerlath.

=== 607 YW ===
* South Guard ceases reporting. Haldric VII sends Deoran, grandson of Haldiel, to investigate. '''The South Guard''' takes place in 607-608 YW.

=== 612 YW ===
* Haldric VII dies. Konrad II is crowned King of Wesnoth.
* Dacyn continues his duties as advisor with Konrad II.

=== 625 YW ===
* Mysterious disappearances of livestock and peasants cause partial evacuation of the the '''Estmark Hills'''. Lords of the Horse Plains report increased banditry from there.
* Konrad II sends [[CharactersStorys#Dacyn|Dacyn]] with [[CharactersStorys#Owaec|Owaec]] and [[CharactersStorys#Gweddry|Gweddry]] to man the old River Guard strongpoints. [[Mainline_Campaigns#The_Eastern_Invasion|'''Eastern Invasion''']] begins.

=== 626 YW ===
* [[CharactersStorys#Mal-Ravanal|Mal-Ravanal]] attacks the middle outpost where [[CharactersStorys#Gweddry|Gweddry]] and [[CharactersStorys#Dacyn|Dacyn]] are stationed.
* Dacyn and Gweddry travel to the northern outpost, and, with [[CharactersStorys#Owaec|Owaec]], retreat into the northlands.
* In the Far North, the wife of Kai Laudiss slain in a large raid by the orcs of Tirigaz on Jotha
* Kai Laudiss slain by poisoned orcish dart during failed attack on the Port of Tirigaz orcs. His son, [[CharactersStorys#Kai_Krellis|Krellis]] succeeds him as Kai and relies on the wisdom of [[CharactersStorys#Cylanna|Cylanna]], a priestess.
* The merfolk city of Jotha is overrun by undead (Mal Kevek and others). The action of [[Mainline_Campaigns#Dead_Water|'''Dead Water''']] takes place.

=== 627 YW ===
* Wesnoth's last defences are broken and the undead march on Wesnoth
* In the northlands, the orcs drive [[CharactersStorys#Gweddry|Gweddry's]] army back across the river.
* Weldyn is besieged.
* Gweddry breaks through undead lines to reach Weldyn and a council is held.
* Gweddry's army is fortunate and kills [[CharactersStorys#Mal-Ravanal|Mal-Ravanal]]. [[Mainline_Campaigns#The_Eastern_Invasion|'''Eastern Invasion''']] ends. [[Mainline_Campaigns#Dead_water|'''Dead Water''']] ends (about this time).
* Wesnoth is saved, but large portions have been laid waste by the undead.
* After destroying [[CharactersStorys#Mal-Ravanal|Mal-Ravanal's]] henchmen the mermen relaxed and began rebuilding in earnest, and soon Jotha was restored.

== 628-673 YW: The Silver Age of Wesnoth ==

The Silver Age, or restoration of the Wesnothian kingdom, essentially coincides with the rest of the long and successful reign of [[CharactersStorys#Konrad_II|Konrad II]]. During this period Wesnoth largely recovered from the damage that Mal-Ravanal's undead attack had done. It would, however, never quite regain the majesty it had at the height of its power.

The Northlands, aided by a second wave of colonization north from Wesnoth, become more civilised and stable. Although nowhere near as prosperous as Wesnoth was during its Golden Age, the Northlands developed towns of significant size and a thriving - if somewhat dangerous - trade network.

Four major powers soon came to dominate much of the Northlands. First there were the dwarves, who controlled most of the mountains and a vast array of underground tunnels and caverns. To the east, shrouded in mystery, lay the elvish forests which continued to be inaccessible to anyone not of elvish blood. The remaining landscape was dominated either by orcish tribes, or independent human earldoms. As competition for the land grew fierce, wars smoldered between human and orcish forces.

=== 628-635 YW ===
* [[CharactersStorys#Konrad_II|Konrad II]] begins his attempt to rebuild Wesnoth.

=== 673 YW ===
* [[CharactersStorys#Konrad_II|Konrad II]] dies, bringing the [[Garardine Dynasty]] to an end. Second Wesnothian civil war begins.

== 786-826 YW: The Legacy of Black-Eye Karun ==

After decades of struggle, Black-Eye Karun becomes the first warlord since the assassination of Great Chief Brurbar in 20 YW to unite all the different squabbling orcish tribes under his banner. Among his many accomplishments as a Sovereign, his most famous is the creation of the Great Council.

Karun was a far-sighted individual and he knew that after his death the orcish tribes would once again turn to fighting among themselves, with little he could do to prevent that and consequent peril from the Wesnothians and elves.

Consequently, Karun selected from among all the different tribes six of the most sober and wisest orcs and thus created the Great Council. It was the Great Council's job to stay aloof from any tribal or territorial squabbling amongst the orcs, but yet always remain there to give advice to whomever came to seek it. In order to preserve the orcish race in the event of an emergency, he invested in them the power to call up The Great Horde. It was established that every orc, no matter what tribe he came from, must obey the summons of The Great Horde and follow wholeheartedly the leader that the Great Council put at the head of The Great Horde.

===786 YW===
* Karun is born.

===805 YW===
* Karun devised the formation of the Great Council.

===811 YW===
* A border dispute between Karun and a human enclave aligned with the Northern Alliance leaves several men and orcs dead and begins a feud that will grow into a fifteen-year war.

===812 YW===
* Rahul I becomes Lord Protector of the Northern Alliance.

===816 YW===
* [[CharactersStorys#Kapou.27e|Kapou’e]] is born

===826 YW===
* Rahul I (Lord Protector of the Northern Alliance) and Black Eye Karun sign a peace treaty ending a 15 year war between the humans and the orcs. Soon after this Karun, is ambushed and killed in mysterious circumstances.

===829 YW===
* Frustrated by the fallout of Karun's supposed assassination, Rahul I resigns, and Howgarth III takes his place as Lord Protector.

===842 YW===
* Famine in the Northlands. Famine led humans to colonize some orcish lands and push orcs into desolated hill country. The few orcish tribes who had remained part of the Alliance, feeling the pressure, either left Alliance territory or revolted and were destroyed.
* Retaliating, the orcs systematically slaughtered human colonies and villages on their lands. Then, Earl Lanbec'h — the most powerful human warlord of the North — determined to abolish the orcish menace raised an army and conferred leadership of it to his son-in-law Baron Alber.
* In response, the Great Council set up by the Black Eye Karun calls upon The Great Horde and bestows leadership of it upon [[CharactersStorys#Kapou.27e|Kapou’e]]; [[Mainline_Campaigns#Son_of_the_Black_Eye|'''Son of the Black Eye''']] begins.

===843 YW===
* Half of the Great Council is treacherously slain by the allied human forces and orcish unity disintegrates. Faced with the extermination of all the orcs on the Great Continent, [[CharactersStorys#Kapou.27e|Kapou’e]] forcibly asserts his control over the orcish territories and defeats the enemy forces. The Northern Alliance arrives on the scene in time for the final battle and helps Kapou’e defeat the forces of the northern earldoms, who had broken the treaty. Kapou’e then assumes the position of Sovereign over the northern tribes, and his rule ushers in an unprecedented era of unity and prosperity for the orcs.
* After 843: Portions of Kapou'e's army act as mercenaries in foreign struggles with other races which keeps them from attacking their nearest neighbors.

===852 YW===
* [[CharactersStorys#Kapou.27e|Kapou’e]] repels a large elvish invasion.

===858 YW===
* The humans once again stage an invasion but prove to be no match for the united orcish forces under the leadership of [[CharactersStorys#Kapou.27e|Kapou’e]]. [[Mainline_Campaigns#Son_of_the_Black_Eye|'''Son of the Black Eye''']] ends.

==After the Great Fall==
At some unknown point in the future, an unspeakable cataclysm scorched the surface of the lands and the God-Demon Zhangor terrorizes the world. The Wesnoth magicians try to raise up a 3rd sun in the sky, Gaia, but they fail and the 'sun' falls down over Weldyn. The capital is no more. The King and his family are dead and there is no heir. The local leaders tear apart Wesnoth. The nights become longer, days hotter. Evil creatures show up. Forests die, hills turn into rocky wastelands and fields become barren deserts. In the apocalypse allies turn against each other and friends fight over what few resources remain. The great nations were destroyed, and huge numbers of people died. Still amidst the chaos somehow small groups of people survived, sheltered in hidden places. In this post-apocalyptic world survival is a daily struggle as a few remaining tribes eke out an existence among the ruins of fallen empires. Heroic bands of elves, nomadic refugee humans, savage hordes of orcs and dark necromancers all forge new lives under the merciless dual suns, Sela and Naia, of this new Irdya. In the meantime an evil entity named Uria arises, scarring the history for life.

===??? Post-Wesnoth===

* The Quenoth elves adapt to life in barren world of the Great Southern Desert. Over time they lost their affinity for the woodlands of their ancestry and embrace life in the sandy wastelands.
* Under the leadership of Tanuil, the Quenoth elves build and sustain a fortified village around a rare oasis. The village thrives amidst the hostilities of the desert.
* One night, a meteor storm rains from the sky and destroys the village of the Quenoth elves. '''Under the Burning Suns''' begins. The next day, Tanuil, like many others, is missing and presumed dead. Kalehssar (Kaleh), nephew of Tanuil, takes leadership of the remaining Quenoth elves as the surviving next of kin.
* Kaleh, heeding the voice of his god Eloh in his dreams, gathers the remaining Quenoth elves and leads them north to a new promised land, foregoing rebuilding of their desert village.
* The Quenoth elves battle their way north through undead, orcs, bandits and other evil, venturing underground beneath a large mountain range at the command of Eloh.
* Befriending unexpected allies underground, Kaleh's forces survive to the other side of the mountain.
* Keratur, son of Tanuil and survivor of the cataclysm, insane with fright attacks Kaleh. Kaleh defeats Keratur.
* Kaleh defies commands given him by a vision of Eloh.
* The Quenoth reach the ocean. Aided by merfolk, they escape the mainland and head for a newly discovered island, a place where the Quenoth may settle in peace.
* On the island, the Quenoth confront Yechnagoth, the Eater of Souls and impersonator of Eloh. Yechnagoth and army are destroyed by the Quenoth.
* Kaleh and the elves settle on their newfound, and newly named, Quenoth Isle. '''Under the Burning Suns''' ends.

== History Credits ==
Timelined by Kamahawk and Turin. Revised to incorporate material from later version of Legend of Wesmere and reconcile different versions of the history of the Sceptre of Fire by Eric S. Raymond.

* History derived from:
** [[The Rise of Wesnoth]]
** [[Legend of Wesmere]]
** [[Delfador's Memoirs]]
** [[Liberty]]
** [[Heir to the Throne]]
** [[Northern Rebirth]]
** [[The Hammer of Thursagan]]
** Eastern Invasion
** [[Dead Water]]
** Under the Burning Suns
* Setting details derived from:
** Invasion from the Unknown

== See Also ==

* [[Geography of Wesnoth]]
* [[Poetry of Wesnoth]]
* [[Races]]
* [[FactionHistory]]
* [[Future History]] '''(unofficial)'''

[[Category:World of Wesnoth]]
[[Category:History]]

InternalActionsWML

2023-12-14T18:25:26Z

Name: Mention and describe "side_name" member and clarify that "team_name" determines which sides are allied.

{{WML Tags}}

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

== Variable Actions ==

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

=== [set_variable] ===

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

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

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

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

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

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

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

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

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

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

* '''abs''': Returns the absolute value of the variable.

* '''root''': Use '''root=square''' to calculate the square root. {{DevFeature1.15|0}} Also supports '''root=cube''' and arbitrary integer roots.

* '''power''': Raise the variable to some power.

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

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

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

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

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

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

* '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:
**'''round=ceil''': Rounds upward to the nearest integer.
**'''round=floor''': Rounds down to the nearest integer.
**'''round=trunc''': {{DevFeature1.15|0}} Rounds towards zero; this is the same operation as '''ipart''', but operating on the value already contained in the variable rather than the value assigned to the key.

* '''min''', '''max''': {{DevFeature1.15|9}} Specify a comma-separated list of numbers; either the smallest or largest number in the list will be assigned to the variable.

* '''reverse=yes''': {{DevFeature1.15|9}} Reverses the string value of the variable. For example, "delfador" becomes "rodafled".

* '''formula''': Calculate the new value of the variable from a [[Wesnoth_Formula_Language|WFL]] formula operating on the old value. This is similar to using the '''$(...)''' syntax but avoids the possibility of WFL syntax errors if a referenced variable is empty.

=== [set_variables] ===

Manipulates a WML array or container

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

* '''mode''': one of the following values:
** ''replace'': will 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'''. Attributes in '''[value]''' will overwrite any existing already in '''name'''. Tags in '''[value]''' modify the corresponding tag of the original value of '''name''', so for example the first '''[attack]''' tag in '''[value]''' would modify the first '''[attack]''' tag of '''name''' rather than appending a new '''[attack]''' tag. A few special syntaxes are supported:
*** ''__remove=yes'': When used in a subtag, causes the corresponding subtag in '''name''' to be deleted rather than merged. Deletion happens after any other subtags have been merged.
*** ''add_to_xxx'': Adds its integer value to the integer value of '''xxx''' in '''name''', and sets '''xxx''' in '''name''' to the result. {{DevFeature1.13|8}} Now adds as real numbers rather than integers.
*** ''concat_to_xxx'': {{DevFeature1.13|8}} Similar to '''add_to_xxx''', but does string concatenation instead of numerical addition.
** ''insert'': will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index greater than (or equal to) the array's current length. This limitation may be removed in future versions.

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

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

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

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

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

=== Capturing Game Data ===

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

==== [store_gold] ====

Stores a side's gold into a variable.

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

==== [store_locations] ====

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

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

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

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

==== [store_reachable_locations] ====

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

* '''[filter]''': a [[StandardUnitFilter]]. The locations reachable by any of the matching units will be stored.
* '''[filter_location]''': (optional) a [[StandardLocationFilter]]. Only locations which also match this filter will be stored.
* '''range''': possible values ''movement'' (default), ''attack'', ''vision''. If ''movement'', stores the locations within the movement range of the unit, taking Zone of Control into account. If ''attack'', stores the attack range (movement range + 1 hex). See note below for ''vision''.
* '''moves''': possible values ''current'' (default), ''max''. For ''movement'' and ''attack'', specifies whether to use the current or maximum movement points when calculating the range. Ignored for ''vision''.
* '''viewing_side''': If left unset then fog and shroud are ignored, hidden ambushers are not ignored, and the real reach of the units is stored. If set to a non-zero number, then the area stored for each unit matching the SUF is based on the information visible to that unit's side; it doesn't matter which non-zero number is given. Ignored completely for ''vision''.
* '''variable''': the name of the variable (array) into which to store the locations.

In 1.14 and before, the ''vision'' range is calculated as max movement range ignoring ZoC + 1 hex.

{{DevFeature1.15|12}} ''vision'' uses the same calculations as the fog and shroud, and handles:
* units with vision costs different to movement costs
* units whose vision points aren't the same as their max movement points
* jamming by enemy units

==== [store_map_dimensions] ====

Stores the map dimensions in a variable.

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

==== [store_side] ====

Stores information about a certain side in a variable.

'''Keys:'''
* '''[[StandardSideFilter]]''': All matching sides are stored. (An array is created if several sides match - access it with side[2].team_name and so on.)
* '''variable''': the name of the variable to store the information in (default: "side")
* '''mode''':{{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and sides which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are sides matching the filter. If mode is set to ''append'', the variable will not be cleared, and sides which match the filter will be added to the array after the existing elements.
'''Result'''

Variable will contain following members:
* '''color''': Team color used for ellipses, sprites, and flags. Will be one of the id's found in data/core/team-colors.cfg or a custom color defined by [[GameConfigWML#Color_Palettes|[color_range]]].
* '''controller''': Indicates type of player that control this side. ''Note: In networked multiplayer, the controller attribute may not be the same on all clients. Be very careful or you have OOS errors.''
** '''human''': Human player
** '''ai''': If players assigns "Computer Player" to "Player/Type" in game lobby
** '''null''': If players assigns "Empty" to "Player/Type" in game lobby
* '''fog''': Indicates whether this side is affected by fog of war.
* '''gold''': The amount of gold the side has.
* '''hidden''': (boolean) If 'yes', side is not shown in status table.
* '''income''': Income for this side (base income + all village income. AKA gross income. Note that this is different from the [side] income key).
* '''name''': Name of player.
* '''recruit''': A comma-separated list of unit types that can be recruited by this side.
* '''shroud''': Whether this side is affected by shroud.
* '''side''': The $side_number of the side belonging to this container
* '''side_name''': Translated string representing the side's description.
* '''team_name''': String representing the team's description. Sides with the same team_name are allied.
* '''user_team_name''': Translated string representing the team's description.
* '''village_gold''': The amount of gold given to this side per village it controls per turn.
* '''scroll_to_leader''': (boolean) Whether the game view scrolls to the side leader at the start of their turn.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]). Unless previously specified in [side] or changed with WML (see [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]]), this value may be empty for the default flag animation.
* '''flag_icon''': Flag icon for the status bar for this side (see [[SideWML|[side]]]). Unless previously specified in [side] or changed with WML (see [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]]), this value may be empty for the default flag icon.
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.
* '''defeat_condition''': {{DevFeature1.13|7}} When the side will be considered defeated. See description at [[SideWML]], [[ScenarioWML#Scenario_End_Conditions]]
* '''faction''': {{DevFeature1.13|7}} id of the selected faction, string (multiplayer-only)
* '''faction_name''': {{DevFeature1.13|7}} Name of the selected faction, string (multiplayer-only)
* '''num_units''' {{DevFeature1.13|7}}: The number of units the side currently has on the map.
* '''num_villages''' {{DevFeature1.13|7}}: The number of villages the side currently controls.
* '''total_upkeep''' {{DevFeature1.13|7}}: The number of unit levels the side is currently supporting.
* '''expenses''' {{DevFeature1.13|7}}: The amount of gold the side is currently spending to support units.
* '''net_income''' {{DevFeature1.13|7}}: The income the side gains per turn after expenses.
* '''base_income''' {{DevFeature1.13|8}}: The income the side gains per turn (same as [side] income key)

* {{DevFeature1.13|7}} All other keys and tags of the side that are contained in [[LuaWML:Sides#wesnoth.sides|wesnoth.sides]] .__cfg

==== [store_starting_location] ====

Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' and 'owner_side' (villages only)

* [[StandardSideFilter]]: The starting locations of all matching sides will be stored. If multiple sides are matched, a WML array will be created.
* '''variable''': (default='location'): the name of the variable to store the location in
* '''mode''':{{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and the starting locations of the sides which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are locations matching the filter. If mode is set to ''append'', the variable will not be cleared, and the starting locations of the matching sides will be added to the array after the existing elements.

==== [store_time_of_day] ====

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

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

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

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

==== [store_turns] ====

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

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

==== [store_unit] ====

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

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

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

''Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] and [[ConditionalActionsWML#.5Bforeach.5D|[foreach]]].

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

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

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

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

==== [store_unit_defense] ====

{{DevFeature1.13|9}}

{{DevFeature1.15|7}} Fixed, was broken in 1.15.3

Stores in a variable the defense of a unit on a particular terrain. If terrain or location is not specified, the terrain on which the unit currently stands is used. (Note: it is a WML defense, so the higher it is, the weaker unit's defense is. A footpad on castle has 70% defense, so this function stores the value 30.)

* StandardUnitFilter
* '''loc_x''', '''loc_y''': x and y of a valid map location. The terrain on this location will be used for the defense calculation.
* '''terrain''': The terrain code for which unit defense should be calculated. If '''terrain''' is specified, '''loc_x''' and '''loc_y''' are ignored.
* '''variable''': the name of the variable into which to store the defense. default: "terrain_defense"

==== [store_unit_defense_on] ====

{{DevFeature1.15|7}} Similar to [store_unit_defense], but stores the same number that would be shown in the UI. For example, a footpad on castle has 70% defense, so this stores the value 70.

Takes the same attributes as [store_unit_defense], and defaults to storing the value in "terrain_defense".

==== [store_unit_type] ====

Stores a unit type definition into a variable.

* '''type''': (required) the defined ID of the unit type, for example "Goblin Knight". Do not use a translation mark or it will not work correctly for different languages. A comma-separated list of IDs may also be used to store an array of unit types.

* '''variable''': the name of the variable into which to store the unit type information (default "unit_type")

* '''mode''':{{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable. If mode is set to ''replace'', the variable will not be cleared, and the unit type will overwrite the existing element at the start of the array, leaving any additional elements intact if the original array contained more elements. If mode is set to ''append'', the variable will not be cleared, and the unit type will be added to the array after the existing elements.

==== [store_unit_type_ids] ====

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

==== [store_villages] ====

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

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

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

==== [store_items] ====

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

*'''variable''': name of the wml variable array to use (default "items")
*'''[[StandardLocationFilter]]''' keys as arguments: only items on locations matching this [[StandardLocationFilter]] will be stored
*'''item_name''': {{DevFeature1.15|0}} if given, only items created with a matching '''[item]name=''' will be stored. As of 1.15.0, this does not support comma-separated lists.

==== [store_relative_direction] ====

{{DevFeature1.13|0}}

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

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

==== [find_path] ====

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

*'''[traveler]''': [[StandardUnitFilter]], only the first matching unit will be used for calculation
*'''[destination]''': [[StandardLocationFilter]]
*'''variable''': the variable name where the result will be stored, if no value is supplied 'path' will be used as default name. Each step will be stored in a [step] array inside that variable.
*'''allow_multiple_turns''': default no, if yes also moves that require more than one turn will be calculated.
*'''check_visibility''': default no, if yes the path will not be computed if some hexes are not visible due to shroud.
*'''check_teleport''': default yes; if no, teleport won't be taken in account while computing path.
*'''check_zoc''': default yes; if no, unit ZOCs won't be considered while calculating the path.
*'''nearest_by''': {{DevFeature1.15|2}} possible values "movement_cost" (default), "steps", "hexes"; if the [destination] SLF matches multiple hexes, the one that would need the least movement points to reach may not be the one that's closest as measured by '''hexes''', or closest as measured by steps, from the starting point. This option chooses which measurement to prefer.

More detail about multiple destinations and the return structure is on [[FindPathExplanation]] (moved out of this page because it has an image in it).

This is the structure of the variable returned by [find_path]:
[path]
hexes = non-zero if a path was successfully found.
if the path is calculated to an impassable hex, or the move requires multiple turns
and allow_multiple_turns is no, its value will be 0.
from_x, from_y = location of the unit
to_x, to_y = destination
movement_cost = total movement cost required by unit to reach that hex
required_turns = total turns required by unit to reach that hex
[step]
x, y = location of the step
terrain = terrain of the step
movement_cost = movement cost required by unit to reach that hex
required_turns = turns required by unit to reach that hex
[/step]
[/path]

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

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

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

=== [clear_variable] ===

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

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

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

=== [sync_variable] ===

{{DevFeature1.13|0}}

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

== Other Internal Actions ==

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

=== [fire_event] ===

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

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

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

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

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

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

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

* {{DevFeature1.17|6}} '''[data]''': Additional arbitrary data to pass to the event. In addition to passing custom data, this can be used to set the '''damage_inflicted''' in an attack event or the '''owner_side''' in a village capture event.

=== [remove_event] ===
{{DevFeature1.13|0}} Removes the event with the specified id.

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

=== [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. If the container variable is a WML array, [insert_tag] will insert a different tag for each of its elements.

=== [role] ===

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

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

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

* '''reassign''': {{DevFeature1.13|6}} Can be either yes or no, defaults to yes. If set to '''no''' then first search for a unit that already has this role, and if found use that unit.

* '''search_recall_list''': {{DevFeature1.13|5}} whether to consider units on the recall list when assigning the role. Can be either yes or no, defaults to yes. {{DevFeature1.13|6}} If set to 'only', then units on the map are not considered when assigning the role - only units on the recall list can receive it. If '''reassign''' is '''no''', this setting also affects the search for a unit that already has the role.

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

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

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

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

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

* '''[filter_location]''': a [[StandardLocationFilter]].
* '''[command]''': contains ActionWml that is executed for each of the locations.
* '''num_items''': the number of locations that should be selected. There are several ways of specifying this:
** An integer, giving the exact number of locations to use. (Variable substitution is supported too.)
** {{DevFeature1.15|0}} A percentage, meaning that fraction of the total available spaces.
** {{DevFeature1.15|0}} A [[Wesnoth_Formula_Language|WFL]] formula. It has access to one variable, ''size'', which is the total number of available spaces. In order to identify it as a WFL formula, the entire expression must be enclosed in parentheses. (Do not use a '''$''', as that will cause it to see ''size'' as zero.)
** A Lua expression. As with a WFL expression, it can access the ''size'' variable. {{DevFeature1.15|0}} This is now deprecated.
* '''variable''': The name of the variable that contains the current location during the execution of [command]. This is a container with the attributes x, y, n and terrain.
* '''min_distance''': The minimum distance of 2 chosen locations, a value less than 0 means that the same locations can be chosen more than one time.
* '''allow_less''': If yes, the tag will not show an error in case there were less than num_items locations available.

=== Flow control actions ===

{{DevFeature1.13|2}}

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

* '''[break]''': The nearest enclosing loop immediately stops executing, and control continues with the next action after the end of that loop. If there is no enclosing loop, this is equivalent to '''[return]'''.
* '''[continue]''': The nearest enclosing loop immediately stops executing, and control continues at the beginning of that loop, with any iteration variables updated for the next iteration. If there is no enclosing loop, this is an error.
* '''[return]''': Control immediately returns to the Wesnoth engine. This completely exits the current event, including any nested events, such that the [message] will not be displayed in the below example. No further WML actions are executed in this context. Any separate, subsequent events will be run as usual.
<syntaxhighlight lang=wml>
[event]
name=moveto
[fire_event]
name=return_please
[/fire_event]
[message]
message="Made it back"
[/message]
[/event]
[event]
name=return_please
[return][/return]
[/event]
</syntaxhighlight>

=== [unsynced] ===

{{DevFeature1.13|2}}

Runs the contained actionwml in a unsynced context, that means actions performed inside [unsynced] are not synced over the network. for example
<syntaxhighlight lang=wml>
[event]
name=moveto
{VARIABLE_OP message rand "Hi,Hello,How are you?"}
[message]
message = $message
[/message]
{CLEAR_VARIABLE message}
[allow_undo]
[/allow_undo]
[/event]
</syntaxhighlight>
will print the same message to all clients, but also disallow undoing (regardless of [allow_undo]) for that moveto becasue it requests a synced random seed form the server. However this code
<syntaxhighlight lang=wml>
[event]
name=moveto
[unsynced]
{VARIABLE_OP message rand "Hi,Hello,How are you?"}
[message]
message = $message
[/message]
{CLEAR_VARIABLE message}
[/unsynced]
[allow_undo]
[/allow_undo]
[/event]
</syntaxhighlight>
will not prevent undoing, but might print a different message for each client in a multiplayer game (or during a sp replay), so `[unsynced]` should not be used for actions that actually change the gamestate otherwise you'll get OOS

== Examples ==

=== Using [set_variables] to Create Arrays of WML ===

<syntaxhighlight lang=wml>
[set_variables]
name=arr
mode=replace
[value]
foo=bar
[/value]
[value]
foo=more
[/value]
[/set_variables]
{DEBUG_MSG $arr[0].foo}
{DEBUG_MSG $arr[1].foo}
</syntaxhighlight>

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

=== [insert_tag] Example ===

<syntaxhighlight lang=wml>
[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]
</syntaxhighlight>

This is effectively identical to:

<syntaxhighlight lang=wml>
[event]
name=moveto

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

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

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

Micro AIs

2023-08-16T17:35:11Z

Name: Note how [micro_ai] side= can take a list of sides as of 1.17.0

== A Few General Words about Micro AIs ==

* Micro AIs allow Wesnoth campaign and scenario authors to add new AI functionality without the need for any AI programming. They bring new specialized behavior to Wesnoth that cannot be achieved, at least not easily, by adjusting default AI parameters (such as those described at [[AiWML]]) or with WML code.

* A Micro AI is activated and configured (or deleted) via the [micro_ai] tag placed in an event, requiring only a few lines of WML code. {{DevFeature1.15|?}} Starting in 1.16 the [micro_ai] tag may also be used in [side][ai] or [unit][ai]. These are both shorthands for placing it in the prestart event with "action=add", side set to the side, and in the case of [unit][ai], a [filter] tag set to limit the Micro AI to that one unit.

* '''Before Wesnoth 1.13.6''', the Micro AI behavior was inconsistent when it came to '''hidden enemies and petrified units'''. Some Micro AIs ignored those, while others did not. In some case there was even a potential for AI errors when an AI unit ran into hidden or petrified enemies. As of 1.13.6, this has all been fixed. The Micro AIs now correctly and consistently ignore hidden units and treat petrified units as blocking the hex they are on but having no effect otherwise, in the same way as the default AI does. '''Important notes:'''
** It is not possible to re-include hidden/petrified units via the Standard Unit Filters (SUFs) used by some of the Micro AIs. In fact, if this is attempted, the filters will generally not match any unit.
*** This only applies to SUFs which go directly into the [micro_ai] tag. Any SUF that is a sub-tag of another filter (for example, of a Standard Location Filter) is taken literally and returns all units matching the filter. If hidden or petrified units are to be excluded from such a sub-filter, that needs to be specified directly in that filter.
** We also note that, because all the Micro AIs are written in Lua, it is possible to [[Micro_AIs#Using_Development_.281.13.29_Version_Micro_AIs_in_your_Stable_.281.12.29_Version_Add-on|move a Micro AI's code into one's add-on]] and modify it to whatever scenario-specific behavior is desired (this does not only apply to hidden/petrified units, but to all behavior). Setting up general Micro AI behavior that works in every possible setting is not feasible, but adapting it to work (only) in the specific setting of a given scenario is often quite simple. If you do not know how to do this, please post a message on the Wesnoth forums and we will be happy to help you with it.

* The '''[[AiWML#List_of_AI_Aspects|default AI aspects]] are, for the most part, not taken into account by the Micro AIs'''. For example, unless noted otherwise, specifying a value for ''aggression'' does not change the MAI behavior. The exception is the ''[avoid]'' tag which is taken into account by many Micro AIs (except those for which it would interfere with the Micro AI behavior or those that already use a a [[StandardLocationFilter|Standard Location Filter]] that can be used for the same purpose). This is a feature of the Micro AIs, not a bug. If you feel that a certain default AI aspect should also apply to a Micro AI, please let us know in the [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 Micro AIs Feedback thread].

* '''Before Wesnoth 1.13.7''', the Micro AIs did not all work reliably when the '''AI side is under shroud''' and it may have been necessary to turn shroud off for the side when using a Micro AI. {{DevFeature1.13|7}} The Micro AIs now all work for sides under shroud. They do this by disregarding shroud for terrain purposes when path finding, consistent with default Wesnoth AI behavior, while still ignoring hidden units (including those hidden under shroud) correctly.

* Most Micro AIs in their default setting apply to all units of a side, although many of them provide parameters for filtering the units that should be affected by the new behavior. If the Micro AI is applied only to part of the units of a side, the other units follow the default Wesnoth AI behavior.

* Micro AIs are available in mainline since Wesnoth 1.11/1.12.

== Micro AI Test and Demo Scenarios ==

All Micro AIs described here can be checked out in a number of test and demo scenarios. The easiest way to access the test scenarios is by assigning a hotkey to "Start Test Scenario" in the preferences (as of Wesnoth 1.13.8). Then, simply press the hotkey in the titlescreen and select the desired scenario from the list (e.g. 'micro_ai_test' for the overall "switchboard scenario").

Test scenarios can also be accessed from the command line by typing
path/wesnoth-executable -t micro_ai_test
or (depending on your system and Wesnoth version)
path/wesnoth-executable -tmicro_ai_test
This starts up a "switchboard scenario" in which you can select the Micro AI demonstration scenario you want to check out. Here, ''path/wesnoth-executable'' needs to be replaced by whatever the path and filename of the Wesnoth executable is on your system.

== Setting up a Micro AI ==

Setting up a Micro AI requires only one simple step:
==== Activating and configuring (or deleting) a Micro AI ====

Micro AIs are activated, deleted and configured using the [micro_ai] tag. This tag needs to be placed in [[ActionWML]], that is, in an event, a menu option or the like. As an example, the following code activates the healer_support Micro AI in its default configuration for Side 2 from the beginning of the scenario:
[event]
name=prestart

# Configure the healer support micro AI
[micro_ai]
side=2
ai_type=healer_support
action=add
[/micro_ai]
[/event]
'''Keys required for all Micro AIs:'''
All [micro_ai] tags must contain the following three required keys:
* '''side''': The side for which the Micro AI is to be added, changed or deleted. {{DevFeature1.17|0}} this can be a list of sides.
* '''ai_type''': The type of Micro AI to be added, changed or deleted. See the following sections for allowed values.
* '''action''' (string): The action to take concerning the Micro AI. The following values are allowed:
** ''add'': Add a Micro AI to a side.
** ''change'': Change the configuration of an existing Micro AI. Note that this does not only change the specific parameters provided in the tag, but it replaces the entire existing Micro AI by a new version with the new (and only the new) configuration. It is therefore equivalent to using first the ''delete'' and then the ''add'' action.
** ''delete'': Delete an existing Micro AI from a side.

'''Keys required under certain circumstances:'''
* '''ca_id''': (string) If several MAIs of the same type are used for the same side and one or several of these are to be changed or deleted during a scenario, this key needs to be included so that the [micro_ai] tag knows which of them needs to be changed/deleted. The same is also true if a Micro AI is changed more than once during a scenario. We therefore '''strongly recommend always setting ''ca_id''''' for MAIs which are, or might be, changed or deleted during a scenario.
** '''Note:''' The id(s)/name(s) actually assigned to the CA(s) of the MAI by the engine might be different from the parameter passed here. It is, however, sufficient to use this ca_id with the [micro_ai] tag add/delete/change actions to identify the MAI uniquely. (In other words: you don't have to worry about this if you always use the [micro_ai] tag, but might have to figure out the actual name(s) of the CA(s) if you want to delete or change them manually.)
* Other keys may also be required depending on the Micro AI. In additional, a number of optional keys may be available to configure the AI behavior. See the sections on the individual Micro AIs for details.

'''Required keys for deleting a Micro AI:'''

Only a subset of the keys required for setting up a Micro AI are needed when deleting it. '''side''', '''ai_type''' and '''action'''=delete always need to be provided. '''ca_id''' needs to be given if it was provided when adding the Micro AI (see above for when this is needed).

'''Notes:'''
* The ''add'' and ''change'' actions ignore all keys that do not apply to the respective Micro AI type. The ''delete'' action ignores all keys other than the required keys listed above.

* Some of the Micro AIs use and/or modify default AI components (candidate actions or aspects) when they are added, or reset these components to their default values when they are deleted. Thus, if you have modified the AI yourself using the default CAs or aspects, some of these modifications might be affected, or might be interfering with the Micro AI. The sections below indicate whether a Micro AI modifies any default AI components.

===Combining Different Micro AI Types for the Same Side===

No extra steps need to be taken when combining different Micro AIs on the same side. Simply set up the [micro_ai] tags for all AIs you want to use.

'''Notes:'''
* While it is ''technically'' possible to combine any number of Micro AIs, this does not mean that all Micro AIs work together in practice. Some are not compatible because they control units in contradictory ways.
* Not all combinations that ''should'' work have been tested yet. If you find a combination that you believe should work but doesn't, [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 please let us know] and we will see if that can be fixed.
* The candidate action score almost certainly has to be set (using the ca_score= key) for one or several of the MAIs if several of them are used on the same side.

== Animals Micro AIs ==
=== General Comments on the Animal Micro AIs ===

The Animals Micro AIs are meant to simulate the behaviors of certain types of animals. They are, however, set up so that they can be used with arbitrary unit types and might be applicable in quite diverse situations. The AIs nevertheless remain named after the animals for which they were written originally, so that they are (to some extent) descriptive of their behavior.

Brief descriptions of the AI behaviors are given in the following subsections. To get a better feeling for their behavior, check out the "Animals", "Swarm", "Wolves" and "Dragon" scenarios from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. Note that some of the animal AIs are designed for animal types that do not exist in mainline. In the test scenario, other animal types are therefore substituted for them.

=== Animals AI: Wolves (ai_type=wolves) ===

The Wolves Micro AI organizes all "wolf" units (predators) of the side to hunt in a single pack. They actively chase after the closest prey and try to corner it (not always super successfully), but are easily distracted by other enemy units coming into attack range, to the point where the pack might split up. The wolves can, however, be told to attack only prey units as well as to try to avoid other types of units (such as larger predators). When no prey is left, the wolves wander randomly.

This AI works best for a small number of predators (2 - 5) and sparse prey. Also, the predators should be put on the map in a pack, that is, reasonably close to each other. For a demonstration of the Wolves AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Note that another wolves AI exists, called [[Micro_AIs#Animals_AI:_Multi-pack_Wolves_.28ai_type.3Dwolves_multipacks.29|Multipack Wolves]], which distributes the wolves of a side into several packs, rather than all of them into one single pack as it is done here.

Enable the Wolves Micro AI by using
ai_type=wolves
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the predator units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the prey units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''attack_only_prey'''=no: In the default configuration, the wolves attack all enemy units in attack range. If this key is set to 'yes', they only attack prey units.
* '''avoid_type''': Comma-separated list of unit types (on enemy sides) which the wolves try to avoid. They try to stay out of these units' way as much as possible when moving around (except when they are moving in to attack another enemy unit) and never attack them.
* '''ca_score'''=90000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 90,000, which is lower than the default combat CA, but higher than most other default CAs which move units. It can be changed by setting this parameter but in most cases this will not make sense. Note that the Wolves AI consists of 2 CAs with scores ranging from <tt>ca_score-1</tt> to <tt>ca_score</tt>.

'''Notes on default (RCA) AI aspects:'''
* If ''attack_only_prey'' or ''avoid_type'' are set, the Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]].
* Attacks by the wolves are left to the default (RCA) AI, meaning that the value of ''aggression'' has an influence on the behavior.
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI is taken into account. Note: as attacks by the wolves are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

Here's an example of a wolves [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=6
ai_type=wolves
action=add

[filter]
type=Wolf
[/filter]
[filter_second]
type=Vampire Bat
[/filter_second]
avoid_type=Yeti,Giant Spider,Ghast,Footpad
[/micro_ai]

=== Animals AI: Multi-pack Wolves (ai_type=wolves_multipacks) ===

The Multi-pack Wolves Micro AI is different from the [[Micro_AIs#Animals_AI:_Wolves_.28ai_type.3Dwolves.29|Wolves Micro AI]] in that there can be an arbitrary number of wolf packs, with the pack size being a free parameter. At the beginning of the scenario, close wolves are grouped into packs in a semi-methodical way. If the wolves are put on the map in distinct groups of close wolves of the correct number, they will be joined into packs matching these groups. If, on the other hand, they are spread out all over the map, the method of assigning them to packs is semi-random.

Wolves of the same pack begin by joining each other on the map. After that, they stay together until only one wolf is left, which then tries to join up with an incomplete pack or with other single wolves. Individual wolves entering the map during the scenario behave in that way as well.

A second difference to the other Wolves AI is that wolves do not actively hunt here. For the most part they just wander (often long distance). However, the pack ferociously (and without regard for its own health) attacks any enemy units that come into range, as long as that does not mean separating the pack by more than a few hexes. Staying together, or joining with a new wolf assigned to the pack, is the only thing that takes priority over satisfying the wolves' thirst for blood.

For a demonstration of the Multi-pack Wolves AI behavior, check out the "Wolves" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Multi-pack Wolves Micro AI by using
ai_type=wolves_multipacks
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

There are no required keys

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Note that the Multi-pack Wolves AI consists of 2 CAs with scores ranging from <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''pack_size'''=3: (integer) The size of the packs.
* '''show_pack_number'''=no: If set to "yes", the wolves' pack numbers will be shown below them. Note that this means that the pack number of a wolf killed in an attack will remain as a label on the map. This behavior is intentional to help UMC authors note where units might have made suicidal mistakes.
* '''type'''=Wolf: Comma-separated list of the unit types which the AI controls. The default value is "Wolf".

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a wolves_multipacks [micro_ai] tag usage from the "Wolves" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=wolves_multipacks
action=add

show_pack_number=yes
pack_size=4
[/micro_ai]

=== Animals AI: Big Animals (ai_type=big_animals) ===

The Big Animals Micro AI is a simulation of large predators that wander and hunt alone, such as Bears, Giant Spiders or Yetis. For the most part, these just wander on the terrain that's been defined for them, but they attack enemy units if those happen to come into range. The AI can be set up so that the Big Animals stay out of the way of other units (such as other large predators), in which case they only attack those if cornered or if they run into them accidentally (such as ambushers).

For a demonstration of the Big Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Big Animals Micro AI by using
ai_type=big_animals
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the animals to which this AI is applied. The filter automatically includes the side= key set to the AI side.

'''Optional keys:'''

* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs.
* '''[filter_location]''': The big animals often go for long distance (multi-turn) journeys. This tag is a [[StandardLocationFilter|Standard Location Filter]] describing the terrain from which the next goal is chosen. The default is all terrain on the map.
* '''[filter_location_wander]''': The terrain on which the big animals will end their moves. This is a [[StandardLocationFilter|Standard Location Filter]]. The default is all terrain on the map.
* '''[avoid_unit]''': A [[StandardUnitFilter|Standard Unit Filter]] describing all enemy units that the big animals will avoid. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

Here's an example of big_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=3
ai_type=big_animals
action=add

[filter]
type=Ghast
[/filter]
[avoid_unit]
type=Yeti,Giant Spider,Ghast,Footpad
[/avoid_unit]
[filter_location]
x,y=1-40,1-18
[/filter_location]
[/micro_ai]

=== Animals AI: Forest Animals (ai_type=forest_animals) ===

The Forest Animals Micro AI simulates a number of different animal behaviors that one might find in a forest, namely animals behaving like deer, rabbits and families of tuskers. In the following, we will refer to those animals by these types, even though the actual unit types can be selected freely. They behave as follows:
* Each deer wanders randomly on (selectable) terrain, except when enemies get in its (the deer's) maximum movement range, in which case it flees to the farthest point it can reach.
* Tuskers exhibit the same behavior as deer, except when an enemy is next to one of the tusklets. This enemy is attacked unconditionally by the tuskers trying to protect their young.
* Tusklets blindly follow the closest adult tusker, except when there is no tusker left, in which case they behave the same as deer.
* Rabbits also wander randomly, but in addition disappear into their holes (if any are within reach) when enemies are close. They reappear out of their holes at the beginning of the turn, if it is safe.

For a demonstration of the Forest Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Forest Animals Micro AI by using
ai_type=forest_animals
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

There are no required keys

'''Optional keys:'''

* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Note that the Forest Animals AI consists of 4 CAs with scores ranging from <tt>ca_score-3</tt> to <tt>ca_score</tt>.
* '''rabbit_type, tusker_type, tusklet_type, deer_type''': Comma-separated lists of the unit types behaving as the respective animals. If any of these parameters are not set, those types of animal behavior are skipped by the AI.
* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the terrain on which the forest animals wander when they are not threatened by enemies.
* '''rabbit_number'''=6: (integer) The number of rabbits for the AI to have on the map simultaneously. The AI puts the missing number of rabbits onto the map at the beginning of the AI's turn (when the rabbits come out of their holes).
* '''rabbit_enemy_distance'''=3: (number) Rabbits won't spawn in holes that aren't more than this distance away from all enemies.
* '''rabbit_hole_img''': Rabbit holes are marked by items on the map. If this parameter is set, it must be the file name of the item image. If it is not set, all items on the map are treated as rabbit holes.
** {{DevFeature1.14|10}} Items used for rabbit holes on the map border used to produce an error. Placing them on the map border therefore needed to be avoided on the scenario setup side. They are now automatically excluded from consideration by the AI code.

Here's an example of forest_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=forest_animals
action=add

deer_type=Vampire Bat
rabbit_type=Giant Rat
tusker_type=Ogre
tusklet_type=Young Ogre
[filter_location]
terrain=*^F*
[/filter_location]
[/micro_ai]

=== Animals AI: Herd and Herders (ai_type=herding) ===

The Herding Micro AI sets up an area on the map where a number of herder units (such as sheep dog) control and protect a herd (such as sheep). For convenience, we simply refer to them as sheep dogs and sheep in the following, even though arbitrary unit types can be selected for either.

Sheep dogs try to keep their sheep safe. This involves keeping them inside the herding area, positioning themselves in between the sheep and approaching enemies, and attacking the enemies if those get too close. If no active herding or protecting move is needed, the dogs go to a random location on the perimeter of the herding area.

Sheep wander aimlessly except when a sheep dog is next to them, in which case they run away from the dog. The dogs exploit this by positioning themselves on the outside of the sheep, if possible. Sheep also run away from approaching enemies.

For a demonstration of the Herding AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Herding Micro AI by using
ai_type=herding
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] describing the herder units (e.g. dogs). The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] describing the herd units (e.g. sheep). The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the terrain forming the perimeter of the herding area. In other words, this is the path the herders (dogs) use to patrol around the outside of the herding area. This must be a set of coordinates ''completely enclosing'' the herding area. Here's an example of setting up a rectangular perimeter:
[filter_location]
x=10-20,10-20,10, ,20
y=11, 21, 11-21,11-21
[/filter_location]
Another possibility is by defining the path by certain terrain on the map (as it is done in the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]), in which case the filter can simply look like this:
[filter_location]
terrain=Rb
[/filter_location]
* '''herd_x,herd_y''': The coordinate of one hex (''any'' one hex) inside the herding area. This is needed to define which part of the map is on the ''inside'' of the herding area perimeter defined by [herding_perimeter], and which is the ''outside''. {{DevFeature1.15|0}} '''herd_loc''' can be used instead with a named/special location.

'''Optional keys:'''
* '''attention_distance'''=8: (integer) If an enemy is within this distance of a herd unit, but not as close as ''attack_distance'', the herders try to position themselves in between the enemy and the herd unit.
* '''attack_distance'''=4: (integer) If an enemy is within this distance of a herd animal, the herders attack this enemy.
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Note that the Herding AI consists of 6 CAs with scores ranging from <tt>ca_score-5</tt> to <tt>ca_score</tt>.

Here's an example of a Herding [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=7
ai_type=herding
action=add

[filter]
type=Footpad
[/filter]
[filter_second]
type=Troll Whelp
[/filter_second]
herd_x,herd_y=32,28
[filter_location]
terrain=Rb
[/filter_location]
[/micro_ai]

=== Animals AI: Hunter (ai_type=hunter) ===

The Hunter Micro AI leads a unit (or units) through hunt-and-rest cycles. The units wander in a prescribed area of the map, their hunting ground, until an enemy unit comes within range. Note that the units do not actively chase down enemies, but wander randomly through the hunting ground until an enemy is encountered.

If enemies are within range of a hunter unit, the hunter attacks the weakest of them. If a kill is made, it then retreats to its rest location, where it stays for a certain number of turns and until fully healed (whatever happens later).

A few more details:
* If the hunter's way home is entirely blocked on the return (so that there is no possible path), the normal RCA AI takes over its behavior.
* However, if the way is blocked by an enemy unit occupying the rest hex, that enemy will be attacked unconditionally.
* A kill only makes the hunter go home when it is the attacker, not as defender.

For a demonstration of the Hunter AI behavior, check out the "Dragon" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Hunter Micro AI by using
ai_type=hunter
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|Standard Unit Filter]] selecting the units controlled by this Micro AI.
** One or the other is required
** If both are given, [filter] takes priority over id=
** The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
** If several units match the filter, the order in which they are controlled is not guaranteed. If the order matters, set up several MAIs using the id= key and different values for ca_score=.
* '''home_x,home_y''': The coordinates of the hex to which the hunter returns and rests at after a kill. {{DevFeature1.15|0}} '''home_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs.
* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the unit's hunting ground. If this tag is not provided, the hunter uses all of the map.
* '''rest_turns'''=3: (integer) The number of turns the AI stays at home_x,home_y after a kill. It will not leave its home until this number of turns have passed ''and'' it is fully healed.
* '''show_messages'''=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase. Note that this is meant as debug output for the scenario author. The messages are not translated and are not included in replays (and are only visible to the host in an MP game).

Here's an example of a hunter [micro_ai] tag usage from the "Dragon" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=hunter
action=add

[filter]
id=Rowck
[/filter]
[filter_location]
x,y=5-30,1-15
[/filter_location]
home_x,home_y=3,15
rest_turns=2

show_messages=yes
[/micro_ai]

=== Animals AI: Swarm (ai_type=swarm) ===

The Swarm Micro AI uses some very simply algorithms to simulate animal swarm behavior. Without adjacent enemies, they simply do a random move, trying to stay together and at a certain distance from enemies. However, if an enemy unit is close to any bat, the swarm scatters. This is particular fun to watch when one places an enemy unit in the middle of the swarm. After being scattered, the swarm members slowly rejoin, but not in a very organized way. Sub-swarms or individual bats might roam around for quite some time before they find their way back. It is also possible that individual bats (or small groups) split off from the larger swarm at times.

For a demonstration of the Swarm AI behavior, check out the "Swarm" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Swarm Micro AI by using
ai_type=swarm
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

There are no required keys

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Note that the Swarm AI consists of 2 CAs with scores ranging from <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''enemy_distance'''=5: (int) The minimum distance kept between units of the swarm and enemies when the swarm moves as a whole.
* '''[filter]''': {{DevFeature1.15|12}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the swarm. The filter automatically includes the side= key set to the AI side.
* '''scatter_distance'''=3: (int) Enemies within "scatter_distance" hexes of any swarm unit cause the swarm to scatter, by each unit trying to maximize its individual distance from the enemy.
* '''vision_distance'''=12: (int) Only units within this distance follow the overall swarm motion (either away from an enemy or of the swarm as a whole). The smaller this value is set, the less likely the swarm is to stay together or rejoin. This parameter is meant to simulate how far an individual member of the swarm can see, meaning that the swarm is "out of sight" (and the unit will not be able to follow it) if it is more than this distance away.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a Swarm [micro_ai] tag usage from the "Swarm" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=swarm
action=add
[/micro_ai]

== Assassin Squad Micro AI (ai_type=assassin) ==

{{DevFeature1.13|6}}

This Micro AI controls one or several assassin units which try to circle around enemy units with the goal of hitting a target unit without being distracted or impeded by other enemies. The units will always attack the target if such attacks are possible, otherwise they will follow the path of least resistance toward it. Notes:

* The main priority for the AI is to find paths that avoid enemy units. However, if no such path can be found, the assassins will still advance toward the target, taking the path exposing the units to the least potential damage from enemies.

* The units will not necessarily follow the same path. The best path is chosen individually for each unit.

* While it is not a requirement for the AI to work, using ambusher or skirmisher units, or units with the quick trait, makes this AI more lethal in many cases.

* The CA evaluation scores of this AI are hard-coded, it does not work otherwise. That means that '''ca_score''' is not a valid key for the [micro_ai] tag.

Enable the Assassin Squad Micro AI by using
ai_type=assassin
in the [micro_ai] tag.

===Assassin Squad specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the assassin units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the target unit.
** It is important to realize that the AI currently only works correctly with a single target unit. It is thus the responsibility of the scenario designer to make sure that this filter matches an individual enemy unit. If several enemy units are to be targeted in the same scenario, several instances of the Assassin Micro AI can be used.
** The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''[prefer]''': A [[StandardLocationFilter|Standard Location Filter]] selecting locations on the map for the assassins to prefer when making their way toward the target unit. This could be used, for example, to make units with the ambush ability move (mostly) through forest or to have the assassins circle around the, say, northern part of the map rather than the south if that is desirable for scenario design purposes.
** As with avoiding enemies, the units will still move across non-preferred terrain if that is either the only option or ''much'' shorter than preferred terrain
** Attacking, once the target unit is in range, is not influenced by the [prefer] SLF.

Here is an example of an Assassin Squad [micro_ai] tag usage:
[micro_ai]
side=2
ai_type=assassin
action=add

[filter]
type=Assassin,Master at Arms,Duelist
[/filter]
[filter_second]
id=Konrad
[/filter_second]
[prefer] # Circle around northern part of map
x=1-9, 10-99
y=1-37, 1-17
[/prefer]
[/micro_ai]

== Bottleneck Defense Micro AI (ai_type=bottleneck_defense) ==

The Bottleneck Defense Micro AI lets you define a location on the map where the AI can take a defensive stance behind a narrow passage (bottleneck). Units on the front line are backed up by healers and/or units with the leadership ability. Injured units are moved to the back and replaced by uninjured (or less injured) units. The units on the front line only attack when it is safe (no retaliation) or when there is a high chance that they will make a kill or level up. Using this Micro AI only makes sense if there is no way for the enemy sides to move around the bottleneck and attack the AI's units from behind.

For a demonstration, check out the "Bottleneck" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Bottleneck Defense Micro AI by using
ai_type=bottleneck_defense
in the [micro_ai] tag.

===Bottleneck Defense specific keys for the [micro_ai] tag:===

'''Required keys:'''

The Bottleneck Defense AI requires two sets of coordinates that define where it should be taking up its defensive stance, and from which side the enemy attacks at that location.

* '''x,y''': Comma separated lists of the hexes on the front line, where strong units are placed. All hexes on which the AI makes contact with (can be attacked by) the enemy need to be included here. Units are placed on them in the order in which they are listed here. {{DevFeature1.15|0}} '''location_id''' can be used instead with named/special locations.
* '''enemy_x,enemy_y''': Comma separated list of the hexes from which the enemy can attack the AI front line units. This is needed for the AI to know on which side of the front line support units (healers etc.) need to be placed. In many cases, it is sufficient to provide only one of the enemy front line hexes, but there are geometries for which that does not work. It is therefore safer to list all enemy front line hexes here. {{DevFeature1.15|0}} '''enemy_loc''' can be used instead with named/special locations.

'''Optional keys:'''

By default, the AI places healers and units with the leadership ability both on the front line itself (if they are the strongest units available) and on hexes adjacent to and behind the line. If different placement is desired, these locations can be overridden with the following keys.

* '''active_side_leader'''=no: (boolean) If set to 'yes', the side leader participates in the bottleneck defense action after the side's gold has been spent. If set to 'no' (default), the leader follows default AI behavior (sitting on the keep and recruiting, for the most part).
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Note that the Bottleneck Defense AI consists of 2 CAs with scores ranging from <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''[filter]''': {{DevFeature1.15|3}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the bottleneck defense. The filter automatically includes the side= key set to the AI side.
* '''healer_x,healer_y''': Comma separated list of hexes where healers are placed. This can be used to keep healers from the front line (or to take up only certain positions on the front line), and/or to override the default healing positions behind the line. Healers are placed on them in the order in which the hexes are listed, with the exception that hexes on the line always take priority over hexes behind the line. {{DevFeature1.15|0}} '''healer_loc''' can be used instead with named/special locations.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability. {{DevFeature1.15|0}} '''leadership_loc''' can be used instead with named/special locations.

As an example, in the "Bottleneck" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]], there are three front line hexes, two of which are on hill terrain, while the third is a road with a lower defense rating. The healer and side leader are supposed to participate in combat because they are strong units, but only from the hill hexes to keep them safer. This is accomplished by using the following keys settings (check out the scenario to see which hex is which):
[micro_ai]
side=1
ai_type=bottleneck_defense
action=add

x=14,14,14
y= 7, 9, 8
enemy_x=13,13
enemy_y= 8, 9

healer_x=14,14,15,15
healer_y= 7, 9, 8, 9
leadership_x=14,14,15,15
leadership_y= 7, 9, 9 ,8
active_side_leader=yes
[/micro_ai]

== Fast Micro AI (ai_type=fast_ai) ==

{{DevFeature1.13|0}}

This AI is meant as a fall-back AI for scenarios where there are so many units that attacks and moves done by the default AI are slow with long delays before each move. It replaces the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions (CAs). It should be obvious that in order to achieve the faster speed, compromises concerning the quality of the moves have to be made.

Enable the Fast Micro AI by using
ai_type=fast_ai
in the [micro_ai] tag.

'''Combat candidate action:'''
* Attackers are considered individually one at a time. The best attack found for a unit is executed without checking whether a better attack by another unit might be possible.
* The default order in which attackers are considered is by decreasing hitpoints, starting with the strongest unit (in terms of HP). This can be modified with the optional keys below.
* By default, if weaker units block attack hexes for a stronger unit, they do not move out of the way (this is the same as for the default AI). If a hex becomes available after an attack (e.g. due to a weaker unit dying in the attack), all attacks that were possible ''before'' this happened are finished first. Only after that are attacks by the stronger unit reconsidered.
* If include_occupied_attack_hexes=yes is set, weaker units move out of the way for stronger units if possible. This can, however slow down the AI depending on the situation on the map. Use with caution.
* {{DevFeature1.13|2}} Previous to this version, attacks by the leader were bunched in with the attacks by the other units. Now leader attacks are treated separately and contain an extra layer of analysis to determine whether the attack position is "safe" (in an approximate way). Currently, this is done with two simple considerations:
** Count all enemy units that can reach the leader's attack position. If there are more than given by optional parameter 'leader_attack_max_units' (default value 3), do not attack.
** Add up the hitpoints of all enemies that can reach the leader's attack position. If this value, multiplied by optional parameter 'leader_weight'(default value 2), is larger than the leaders hitpoints, do not attack.
** Two optional parameters, 'threatened_leader_fights' and 'leader_additional_threat', can also be used to let the leader attack when the threat at the attack hex is comparable to that at the leader's current position.
** In order to keep this AI as fast as possible, leader attacks are done by a separate candidate action that is only evaluated when all other CAs are done.

'''Move-to-targets, villages and retreat candidate actions:'''
* The move-to-targets, villages and retreat candidate actions of the default AI are removed. Move-to-targets and villages are taken over by the Fast Micro AI, whereas retreat is simply not done.
* This CA moves units toward goals after attacks are done. Goals are unowned (if the AI side has a leader only) and enemy-owned villages and enemy leaders.
* For each goal, units are pre-sorted in order of the fewest moves needed to cover the ''distance'' toward the goal (that is, as if move cost on each hex toward the goal were 1). Units are then considered sequentially and if a unit can get there "efficiently", its move is executed without considering other units.
** A move is considered efficient if the move cost to get to the hex is not more than 'move_cost_factor' larger than the distance to the hex. 'move_cost_factor' is an optional key that defaults to 2. It can be set to values of 1.1 or larger (see below).
** If the move for the current unit is not found to be efficient, the AI considers the next unit instead. If no unit can do an efficient move toward the goal, the best (fastest) of the inefficient moves is selected instead.

* Village goals:
** Village goals are considered before enemy leader goals so that the AI preferentially chooses scouts (or otherwise fast units) for them.
** The number of units sent toward villages depends on the value of the default AI aspect village_value. It is set to village_value/4 times the number of units the AI has left to move. Thus, by default (village_value=1.0) the AI sends a quarter of its units toward villages, and the rest toward enemy leaders. This means that the meaningful range of values for village_value is 0..4.
** Only one unit is moved toward each village. This consideration also overrides the number of units to move toward villages defined by village_value, topping it at the number of unowned/enemy-owned villages on the map.
** Setting village_value=0 disables moving units toward villages altogether. That is, not only are no units chosen, but the village targeting phase of the AI is entirely disabled with no evaluation time used for it. Note that, unlike with the default AI, this also means that no villages within range of an AI unit are grabbed.
** The order in which villages are chosen as goals is some combination of them being close to the AI side's leader and being spread out over the map.

* Enemy leader goals:
** The order of enemy leaders goals is set according to their distance from the AI leader with the closest enemy leader being targeted first (if the AI has a leader, otherwise their order is random). One unit is sent toward each enemy leader in this order, after which the AI starts with the first enemy leader again. This is repeated until all units have moved.

* Guardians (units with ai_special=guardian set) are ignored by the fast move-to-targets CA.

'''Tips for speeding up/modifying the Fast Micro AI in specific scenarios:'''

A number of optional keys and default AI aspects can be used to modify the behavior of the Fast Micro AI. The MAI is set up so that it is a reasonable compromise between speed and quality of the moves in most situations. However, this might not be ideal for all scenarios here are some things that can be done to speed up the AI (or to get better behavior in some situations by doing the opposite):
* Use large values for the default AI aspect aggression. The largest delays before attacks happen (in some circumstances) when the Fast MAI has to consider lots of units with attacks left but decides not to attack with them. See below for a description of how aggression is used by the fast AI.
* Use large values of move_cost_factor (see above for description of what this does). If you want to emphasize units that can move across terrain easily (e.g. bats) to be chosen for village grabbing, you might want to use low values of move_cost_factor, but this might slow down the AI. The default value should work reasonably well in most standard situations, but modifying the value might work better on specific maps.
* Don't use dungeon_mode=yes unless absolutely necessary, even in most dungeon crawls. Test the AI without this setting first and only use it if it is the only way to solve the problem. Often, a minor tweak to the map will have the same effect, without the speed penalty.
* Use include_occupied_attack_hexes=yes with caution. It might (or might not) slow down the attack CA significantly, depending on the scenario.
* Set village_value=0, which makes the AI not consider villages as goals. This has not been found to make a large difference on the maps tested so far, but it might have an effect on maps with a very large number of villages.
* Use attack_hidden_enemies=yes on maps where there are no hidden enemies. Excluding hidden enemies from the attack calculation requires an additional filter to be evaluated that takes extra time. In most cases this will not result in a large computation time saving.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''attack_hidden_enemies'''=no: (boolean) By default, hidden enemies are excluded from the attack calculation. Setting this to 'yes' makes the AI also consider those enemies as attack targets.
* '''[avoid]''': {{DevFeature1.13|2}} A [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). As with the default AI, units will not step on hexes defined by the [avoid] tag. In addition, no goals will be chosen that lie on those hexes. The one minor exception is that a unit stepping out of the way for another unit might temporarily enter the avoided zone.
* '''dungeon_mode'''=no: (boolean) As much as possible, the Fast Micro AI works with distances between hexes rather than path finding. This works pretty well on open maps and even most dungeon crawls (and similar scenarios), but it might result in some units getting temporarily (and in rare cases permanently) stuck on maps with convoluted labyrinths. If that is the case, setting dungeon_mode=yes triggers more path finding that avoids such situations (but as a result is somewhat slower).
* '''include_occupied_attack_hexes'''=no: (boolean) If set to 'yes', the AI moves weaker units out of the way for a stronger attacker. This might lead to better attacks but is slower, so don't use if speed is essential.
* '''[filter]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the attackers. Only AI units matching this filter will attack, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes the side= key set to the AI side. It does not affect the move-to-targets CA.
* '''[filter_second]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the enemies. Only enemy units matching this filter will be attacked, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side. It does not affect the move-to-targets CA.
* '''leader_weight'''=2: (number >= 0) {{DevFeature1.13|2}} A factor specifying how much more valuable the AI considers side leaders than non-leader units in the attack evaluation. This is also used to determine whether an attack by the leader is safe (see description of the combat candidate action above).
* '''leader_additional_threat'''=1: (number > 0) {{DevFeature1.13|2}} If threatened_leader_fights=yes, the threat at the attack position may be larger by this factor for the leader to leave the keep for an attack.
* '''leader_attack_max_units'''=3: (number >= 0) {{DevFeature1.13|2}} A number specifying how many enemy units within reach are acceptable when determining whether an attack by the leader is safe (see description of the combat candidate action above).
* '''move_cost_factor'''=2: (number >= 1.1) The factor by which the move cost to a goal hex may be larger than the distance to the goal hex for a move to be considered "efficient". See description above. 1.1 is used if this is set to values smaller than 1.1. Smaller values might lead to better behavior, while larger values might speed up the AI.
* '''weak_units_first'''=no: (boolean) If set to 'yes', inverts the order in which units are considered by the combat CA. Attacks are then done in order of increasing hitpoints of the attackers.
* '''skip_combat_ca'''=no: (boolean) If set to 'yes', the fast combat CA is not used. The default AI's high_xp_attack and combat CAs remains in place in this case.
* '''skip_move_ca'''=no: (boolean) If set to 'yes', the fast move-to-targets CA is not used. The default AI's retreat, villages and move-to-targets CAs remains in place in this case.
* '''threatened_leader_fights'''=no: (boolean) {{DevFeature1.13|2}} By default, the AI leader will not attack if the threat at the attack position is too high. If this key is set to 'yes', the leader will attack if the threat there is not larger than the threat at his current position multiplied by the value of 'leader_additional_threat'. This is meant as an option for the endgame: when the AI leader is under attack, he might as well go down fighting.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''aggression''': The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to set how aggressive the AI should attack. It works in roughly the same way as the default AI aspect:
** The value of (1 - aggression) determines how much the AI values its own units compared to the enemy's units. Thus, aggression=0 means that attacks are only done if the AI expects to deal (roughly) the same amount of damage as it will receive. aggression=1 means that expected damage to the AI's units is not considered, only the expected damage to enemy units matters.
** Damage is calculated as a combination of hitpoints and chance to die, in "gold equivalent units".
** Unlike the default AI, aggression is set to 1 for values larger than 1. Allowed values are thus anything from -infinity to +infinity, although only -infinity to +1.0 make sense.
*'''[avoid]''': {{DevFeature1.13|2}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.
*'''attacks aspect''': {{DevFeature1.13|2}} The standard RCA AI [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] used to filter own and enemy units for attacks is now also taken into account as long as neither [filter] nor [filter_second] (see above under 'optional keys') are defined in the [micro_ai] tag.
*'''village_value=1''': (number ranging from 0 to 4) The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to define how much villages should be targeted by the move-to-targets CA. In the Fast MAI, this defines which fraction of the AI units are moved toward village goals (see above for details). If set to 0, villages are ignored as goals.

'''Notes:'''
* The CA evaluation scores of this AI are hard-coded to the same values as those of the respective [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|default candidate actions]]. ca_score is therefore not a valid optional key.
* The fast Micro AI modifies (removes) the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions.

Enabling the Fast Micro AI in its default configuration is as simple as this usage example from the "Fast AI" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=fast_ai
action=add
[/micro_ai]

== Generalized Goto Micro AI (ai_type=goto) ==

The Goto Micro AI provides a highly configurable method of sending a unit (or units) to a location or set of locations. The units to be moved are defined using a [[StandardUnitFilter|Standard Unit Filter]] (SUF) [alternatively, all side units are used if the SUF is not provided), while the goto locations are given in a [[StandardLocationFilter|Standard Location Filter]] (SLF).

By default, each unit matching the SUF will move toward the closest goal (in terms of turns needed to get there) matching the SLF via the fastest route given the current situation on the map (locations of enemy units etc.), but this behavior can be influenced by the optional keys listed below. Note that this means that a unit's goal might change from one turn to the next depending on the situation on the map.

The behavior of the unit(s) once they reach their goal location(s) is configurable as well. By default, they will stay there until the Goto Micro AI is deleted or changed.

For demonstrations of several Goto Micro AI usages, check out the "Goto" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Goto Micro AI by using
ai_type=goto
in the [micro_ai] tag.

===Goto specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the possible goal locations for the move.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). Note that the area defined by [avoid] is not entered at all, even if the end point of the move would lie outside the area again.
* '''avoid_enemies''': (number>0) By default, units controlled by the Goto Micro AI will not take enemy units into account for route finding, other than the enemies' ZoCs. By contrast, if this key is set, they will try to avoid traversing hexes on which they can be attacked by enemies. The larger the value of ''avoid_enemies'', the more the units will try to stay out of the enemies' way. Notes:
** Units are willing to take a path that is 'avoid_enemies' movement points longer for each enemy unit that can be avoided by doing so for each hex along the path. As an example, if avoid_enemies=1 and the shortest path crosses 2 hexes that can be reached by 3 enemies each, the unit is willing to take a path that is up to 6 hexes longer instead. If avoid_enemies=10 in the same situation, the unit will take a path up to 60 hexes longer.
** Hexes adjacent to enemy units are always strongly avoided, independent of the value of avoid_enemies.
** avoid_enemies is ignored if 'use_straight_line=true' is set.
** Due to an issue with the path finding code, '''tunnels and teleports are ignored in Wesnoth 1.14 and before''' if 'avoid_enemies' is used. This has been fixed in Wesnoth 1.15.
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs.
* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units to be moved. Defaults to all units of the side if not defined. The filter automatically includes the side= key set to the AI side.
* '''ignore_enemy_at_goal'''=no and '''ignore_units'''=no: (boolean) In the default configuration, the Goto MAI does not move units if the path to all goal hexes is blocked by enemies. It is therefore possible to disable the Goto MAI by putting enemy units on all the goal hexes. That can be changed if either of these two keys is set to 'yes'.
** 'ignore_enemy_at_goal=yes' makes the AI choose its goals while disregarding any enemy units at the goal hexes. Even so, a stiff rating penalty is applied to goal hexes occupied by enemies, thus that unoccupied goal hexes are chosen unless all possible goals are occupied by enemies. Note that this setting ''only'' ignores enemy units at the goal hexes themselves. It is still possible to disable the AI by putting enemies all around the goals.
** 'ignore_units=yes' let's the AI ignore ''all'' enemy units when deciding which goal hex(es) to move toward.
** In both cases, enemies are only ignored for deciding which unit to move toward which goal hex. For the actual move itself, all enemies and their ZoCs are considered as usual.
** Both options only take effect if neither avoid_enemies is used, nor use_straight_line is set to 'yes', as neither of these consider enemies as blockers. Or in other words, if avoid_enemies is used, or use_straight_line=yes, it is unnecessary to set ignore_enemy_at_goal or ignore_units to yes.
* '''release_unit_at_goal'''=no: (boolean) By default, a unit that reaches a goal location will stay there until the Goto Micro AI is deleted or changed (or until the conditions specified in the [goto_goals] SLF change). If this parameter is set, a unit that has reached its goal will not be controlled by this Micro AI any more starting from the next turn.
* '''release_all_units_at_goal'''=no: (boolean) Same as ''release_unit_at_goal'', but this will deactivate the Goto Micro AI for all units once the first unit reaches a goal.
* '''remove_movement'''=yes: (boolean): {{DevFeature1.15|11}} By default, when the Goto MAI cannot move a unit (for example, because the path is blocked by enemies), its movement points are still removed. If this option is set to 'no', this step does not happen, so that other AI candidate actions (or even another Goto MAI with different parameters) can take over instead.
* '''unique_goals'''=no: (boolean) If set to 'yes', each unit will be sent to a different goal location. Note that the best goals are recalculated each turn, so a unit might choose a different goal this turn from what it was heading for during the previous turn if the situation on the map has changed. Also note that if there are more units than goal locations, the left over units will not be handled by the Goto MAI but follow default behavior instead.
* '''use_straight_line'''=no: (boolean) By default, units choose the route by which they will get to their goal locations in the smallest number of turns. If this parameter is set to 'yes', a straight line route (or something pretty close to it at least) will be chosen instead, irrespective of whether this leads into a dead end, whether it is blocked by enemies, etc.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

'''Notes:'''
* Depending on the parameters used, the Goto Micro AI might require a lot of path finding to be done. Thus, while it is possible to set up this AI to move many units to many different locations, a usage like that might require quite a long calculation time.

===Goto Micro AI example usages:===

Here are several examples of goto [micro_ai] tag usages from the "Goto" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
* Send a unit toward a castle (similar to the RCA AI's Goto Candidate Action, but avoiding dead ends and areas ZoCed by enemies)
[micro_ai]
side=2
ai_type=goto
action=add
ca_id=messenger1

[filter]
id=messenger1
[/filter]
[filter_location]
x,y=6-7,2-4
terrain=C*
[/filter_location]
ca_score=210001
[/micro_ai]
* Send all units of the side toward the southern border of the map
[micro_ai]
side=8
ai_type=goto
action=add

[filter_location]
y=33
[/filter_location]
avoid_enemies=1
[/micro_ai]
* Send units to the four corners of the map (with each unit going to a different corner).
[micro_ai]
side=7
ai_type=goto
action=add

[filter_location]
x=1,1,44,44
y=1,33,1,33
[/filter_location]
unique_goals=yes
[/micro_ai]
* Set up a guardian unit that doesn't move while no enemy unit is within 8 hexes (ironically, the Goto Micro AI can be used to keep units in place, although using one of the Guardian Micro AIs might often be a better idea)
[micro_ai]
side=3
ai_type=goto
action=add

[filter]
id=guard1
[/filter]
[filter_location]
[filter]
id=guard1
[/filter]
[not]
[filter]
side=1
[/filter]
radius=8
[/not]
[/filter_location]
[/micro_ai]

== Guardian Micro AIs ==
=== General Comments on the Guardian Micro AIs ===

The Guardian Micro AIs can be used to set up different kind of guardian behaviors for a unit or a set of units. Four different types of guardians are available and are described below.

For a demonstration of several different guardian behaviors, check out the "Guardians" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

=== Return Guardian (ai_type=return_guardian)===

A 'return guardian' is a variation of the standard Wesnoth guardian. It has an assigned guard position (GP) to which it returns after attacks on approaching enemies:
* If at GP with no enemy in reach, do nothing.
* If at GP with an enemy in reach, attack. Note that the attack is done by the default AI, which might result in the guardian not attacking if the enemy is deemed too strong (this can be influenced by setting the default ''aggression'' value to a different value).
* If not at GP, return there, no matter whether an enemy is in reach or not.
* If enemies are blocking the way back to GP, do your best to move around them.
* If the guardian ends up next to an enemy on the way back, attack that enemy after the move.

Enable the Return Guardian Micro AI by using
ai_type=return_guardian
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|Standard Unit Filter]] selecting the units controlled by this Micro AI.
** One or the other is required
** If both are given, [filter] takes priority over id=
** The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
** If several units match the filter, the order in which they are controlled is not guaranteed. If the order matters, set up several MAIs using the id= key and different values for ca_score=.
* '''return_x,return_y''': The coordinate of the hex the unit returns to after each attack. {{DevFeature1.15|0}} '''return_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=100010: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. This AI consist of 2 CAs, one with score <tt>ca_score</tt> the other with <tt>ca_score-20</tt>. The default value is set so that the first CA gets executed right before the default combat CA, and the other right after. It usually will not make sense to change this value, but it is possible to do so for custom applications. {{DevFeature1.13|6}}: This is now changed to 100100 and 99900 in order to avoid conflicts with the new high_XP_attacks candidate action.

Here's an example of a return guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=return_guardian
action=add

[filter]
id=return1
[/filter]
return_x,return_y=20,2
[/micro_ai]

===Stationed Guardian (ai_type=stationed_guardian) ===

A 'stationed guardian' is another variation of the standard Wesnoth guardian with a somewhat more complex behavior than that of the 'return guardian'. Two positions are defined for it, a 'station' and a 'guarded location', as well as a distance. The behavior is as follows:
* If no enemy is within 'distance' of the guard's current position, do nothing. This is independent of the guardian being at its station or not.
* Otherwise: If an enemy is within 'distance' of the guard, but not also within the same distance of the guarded location and the station (all of this simultaneously), move the guard in the direction of the station (or keep the guard in place if the station is unreachable).
* Otherwise:
** Pick the enemy unit that is closest to the guarded location.
** If we can reach it, pick the adjacent hex with the highest defense rating and attack from there.
** If not in reach, move toward this unit.

Enable the Stationed Guardian Micro AI by using
ai_type=stationed_guardian
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|Standard Unit Filter]] selecting the units controlled by this Micro AI.
** One or the other is required
** If both are given, [filter] takes priority over id=
** The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
** If several units match the filter, the order in which they are controlled is not guaranteed. If the order matters, set up several MAIs using the id= key and different values for ca_score=.
* '''distance''': The distance parameter as explained above
* '''station_x,station_y''': The x and y position of the hex that serves as the guardians station. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.
* '''guard_x, guard_y''': The x and y position of the guarded location. {{DevFeature1.13|0}} These are now optional keys, defaulting to station_x,station_y if not provided. {{DevFeature1.15|0}} '''guard_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs.

Here's an example of a stationed guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=stationed_guardian
action=add

[filter]
id=stationed1
[/filter]
distance=4
station_x,station_y=2,14
guard_x,guard_y=3,13
[/micro_ai]

=== Coward (ai_type=coward) ===

Cowards are units that, like guardians, sit around doing nothing until an enemy comes into range. Unlike guardians, however, they run away once enemies approach. Applications might be wild animals, unarmed civilians getting in the way of a battle, etc. The coward macro can be called with two optional locations, 'seek' and 'avoid':
* If neither is given, the coward retreats to the position farthest away from the approaching enemies.
* If 'seek' is given, it preferentially goes toward that location (but getting away from enemies takes priority).
* If 'avoid' is given, it in addition tries to avoid that location (with both maximizing distance from enemies and going toward 'seek' taking priority).
* Both 'seek' and 'avoid' may consist of only one coordinate ('x' or 'y'), in which case not a single hex, but a line of hexes is sought or avoided.

Enable the Coward Micro AI by using
ai_type=coward
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|Standard Unit Filter]] selecting the units controlled by this Micro AI.
** One or the other is required
** If both are given, [filter] takes priority over id=
** The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
** If several units match the filter, the order in which they are controlled is not guaranteed. If the order matters, set up several MAIs using the id= key and different values for ca_score=.
* '''distance''': The distance within which an enemy must be to "scare" the unit

'''Optional keys:'''

* '''attack_if_trapped'''='no': {{DevFeature1.13|0}} With the default settings, a coward never attacks. If this key is set to 'yes', the coward attacks the weakest (lowest hitpoints) enemy next to which it ends up after moving (such as a cornered animal would do, blindly lashing out without regards for its own safety).
* '''avoid_x, avoid_y''': The x and y coordinate of the hex to avoid. {{DevFeature1.15|0}} '''avoid_loc''' can be used instead with a named/special location.
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units from which the cowards flee. If not set, this defaults to all enemy units. Note, however, that no "enemy of AI side" condition is added if [filter_second] is specified, meaning that it can include allied and/or enemy units as desired (and even units on the same side as the coward).
* '''seek_x, seek_y''': The x and y coordinate of the hex to seek. {{DevFeature1.15|0}} '''seek_loc''' can be used instead with a named/special location.

Here's an example of a coward [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=coward
action=add

[filter]
id=coward3
[/filter]
distance=5
seek_x,seek_y=24,5
avoid_x,avoid_y=24,15
[/micro_ai]

=== Zone guardian (ai_type=zone_guardian) ===

A zone guardian is a unit that, as the name says, guards a zone. It moves randomly inside this zone until an enemy enters it (or a separately defined enemy zone, see below). Applications might be the defense of a castle, a nesting area or for protecting an unit. The zone macro can be called with an optional SLF, [filter_location_enemy]:
* If not specified, the zone guard attacks any enemy coming inside its guard zone.
* If [filter_location_enemy] is given, it attacks any enemy entering this zone and once there are no more enemies, it goes back to patrol in its basic zone.

Enable the Zone Guardian Micro AI by using
ai_type=zone_guardian
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|Standard Unit Filter]] selecting the units controlled by this Micro AI.
** One or the other is required
** If both are given, [filter] takes priority over id=
** The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
** If several units match the filter, the order in which they are controlled is not guaranteed. If the order matters, set up several MAIs using the id= key and different values for ca_score=.
* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] designating the zone to guard.

'''Optional keys:'''
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs.
* '''[filter_location_enemy]''': A [[StandardLocationFilter|Standard Location Filter]] designating the zone where enemies have to be attacked. If not given, it defaults to [filter_location].
* '''station_x,station_y''': By default, the zone guardian moves randomly within the zone if there is no enemy to attack. However, if station_x/y is given, it moves to this position instead during turns when it does not have an enemy to attack. This position does not need to be inside the zone defined above. Note: obviously it does not make sense to define [filter_location], [filter_location_enemy] and station_x/y all at the same time. Only [filter_location] and either one of the latter two (or none of them) should be provided for any zone guardian. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.

Here's an example of a zone guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=zone_guardian
action=add

[filter]
id=zone3
[/filter]
[filter_location]
x,y=22-31,4-11 # This is intentionally chosen to extend past the lake
terrain=W*
[/filter_location]
station_x,station_y=32,8
[/micro_ai]

== Hang Out Micro AI (ai_type=hang_out) ==

The Hang Out Micro AI instructs units of the AI side to "hang out" around a certain location, or locations, until a condition for mobilizing the side is met. If none of the optional keys are given, the AI controls all units of the side to hang around the leader while moving off castle tiles to make room for recruiting.

The AI works by moving each unit to its best hex first using the minimum amount of movement points required for this move. Once all AI units are in position, movement points are set to zero for all of them simultaneously such that they cannot be used by other AI candidate actions. This is done because the mobilizing condition might be met as result of one of the moves of the Hang Out AI, after which we want units to be able to continue with other AI actions.

For a demonstration, check out the "Hang Out and Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Hang Out Micro AI by using
ai_type=hang_out
in the [micro_ai] tag.

===Hang Out specific keys for the [micro_ai] tag:===

'''Required keys:'''

There are no required keys. In its default configuration, the Hang Out MAI controls all units of a side, keeping them as close to the side leader(s) as possible while moving off castle tiles to make room for recruiting. For this purpose, the candidate action score defaults to 170,000, which is just below the score of the default recruiting CA.

'''Optional keys:'''

* '''[avoid]''': A [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). If neither of these two exists, this parameter is set to default to all castle terrain (<tt>terrain=C*,C*^*,*^C*</tt>) so that units move off the castle to make room for recruiting. Note that this does not include keep terrain, otherwise the leader would be moved off the keep as well.
* '''ca_score'''=170000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 170,000, which means that it is executed after the default recruitment CA, but before most of the other default CAs.
* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Hang Out action (<tt>side=</tt> is always set and does not need to be provided). It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the locations ''near'' which the AI units should hang out. This does not mean that the units only move onto terrain specified here, but that they minimize the distance to such terrain. It defaults to the position of the side leader(s).
* '''[mobilize_condition]''': Contains ([[ConditionalActionsWML#Condition_Tags|WML Condition Tags]]) Once the condition set up here has been met, the Hang Out MAI is disabled and the side goes over to other AI activity. The Hang Out MAI remains disabled after this, even if the condition is not met any more later in the scenario.
* '''mobilize_on_gold_less_than''': (integer) Since side gold cannot be checked in a WML condition tag without storing it in a variable first, this key is provided separately. It disables the Hang Out Micro AI once the side gold goes below the value specified here for the first time.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

'''Notes:'''

* The Hang Out AI still takes effect if no locations to hang out at are found or if all map locations are to be avoided. In that case, it simply keeps all units at their current locations.

This is an example of a Hang Out Micro AI configuration from the "Hang Out and Messenger" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=hang_out
action=add

[avoid]
terrain=C*,H*,M*,A*,S*,*^F*
[/avoid]
[mobilize_condition]
[have_unit]
side=1
count=7-99
[/have_unit]
[/mobilize_condition]
[/micro_ai]

== Healer Support Micro AI (ai_type=healer_support) ==

The Healer Support Micro AI configures the healers of a side to stay behind the battle lines and heal injured and/or threatened units rather than participate in combat under all circumstances. You can set different levels of aggressiveness for the healers.

'''Notes'''
* By default, ''all'' healers of the AI side are controlled by this AI. This includes in particular also the side leader, if the leader is a healer. If you do not want the leader to be included (and possibly be moved away from the keep etc.) use the [filter] tag with canrecruit=no (see below).
* It is not always better to use this Micro AI than the default AI, as it takes healers (which can be strong units) away from the pool of units to choose for attacks.
* {{DevFeature1.15|3}} This Micro AI now takes unit guardian status and the passive_leader aspect into account.

For a demonstration, check out the "Healers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Healer Support Micro AI by using
ai_type=healer_support
in the [micro_ai] tag.

===Healer Support specific keys for the [micro_ai] tag:===

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the healer units. If set, only units on the AI side passing this filter ''and'' having the healing ability are considered by this Micro AI.
*'''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting units to receive healing. If set, only units on the AI side passing this filter ''and'' the other healee selection criteria will be selected for healing by this Micro AI.
* '''aggression'''=1.0: (float) Sets the aggressiveness of the AI. This parameter is set up as a float to accommodate future functionality, but it currently acts as a boolean: if set to zero, the AI will never let its healers participate in combat, for all other values it allows them to attack after all other units have attacked and if the healers cannot find any more units to support. The former behavior might be appropriate in scenarios with only one or few valuable healers, while the latter might work better in scenarios with many healers.
* '''injured_units_only'''=no: (boolean) If set to 'yes', the AI will only move healers next to units that are already injured and skip units that currently have full hitpoints, but might get injured during the next enemy turn.
* '''max_threats'''=9999: (integer) The maximum allowable number of enemies that can attack a hex in order for it to be considered for a healer. As an example, setting 'max_threats=0' means that the AI only moves healers to locations that are entirely safe from the enemy (assuming that none of the units currently on the map dies). Note that the value of this key is checked against the number of enemies that can make it to the hex, not the number of adjacent hexes from which the healer could be attacked.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI. Note: as attacks by the healers are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

'''Notes:'''
* The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]].
* The CA evaluation scores of this AI are hard-coded. It does not work otherwise.

This is an example of a Healer Support Micro AI configuration from the "Healers" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=healer_support
action=add

aggression=0
[/micro_ai]

== Lurkers Micro AI (ai_type=lurkers) ==

The Lurker Micro AI controls some or all units of a side in "lurker mode". A lurker is a unit that is capable of moving across most terrains, but that only stops on and attacks from specific terrain. It might also have the ability to hide on this terrain (which is the reason why it is called a lurker).

Lurkers move individually without strategy and always attack the weakest enemy within their reach. If no enemy is in reach, the lurker does a random move instead - or it just sits and waits (lurks).

For a demonstration of different types of lurker behavior, check out the "Lurkers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Lurkers Micro AI by using
ai_type=lurkers
in the [micro_ai] tag

===Lurkers specific keys for the [micro_ai] tag:===

'''Required keys:'''
* '''[filter]''': Specifies which units of the side are controlled by the Lurker Micro AI. This is a [[StandardUnitFilter|Standard Unit Filter]]. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': Specifies the terrain from which the lurkers attack. This is a [[StandardLocationFilter|Standard Location Filter]].

'''Optional keys:'''
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs.
* '''[filter_location_wander]''': Specifies the terrain on which lurkers end their moves if there is no enemy in reach. This is a [[StandardLocationFilter|Standard Location Filter]]. If [filter_location_wander] is not given, it defaults to [filter_location].
* '''stationary'''=no: (boolean) If set to yes, a lurker never moves if there is no enemy within attack range.

Here's an example of [micro_ai] tag usage from the "Lurkers" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=4
ai_type=lurkers
action=add

[filter]
type=Naga Fighter
[/filter]
[filter_location]
terrain=W*,S*
[/filter_location]
[filter_location_wander]
terrain=W*
[/filter_location_wander]
[/micro_ai]

== Messenger Escort Micro AI (ai_type=messenger_escort) ==

The Messenger Escort Micro AI lets you define a set of waypoints through which it tries to move one or several of its units, the messenger(s). The other units escort the messenger, trying to protect it and attacking enemies that are in its way. Note that a messenger might not strictly hit intermediate waypoints, but that getting close is good enough, especially if a waypoint is occupied by an enemy unit. It does, however, always try to get to the last waypoint.

'''Notes on the use of several messengers:''' {{DevFeature1.13|0}}
* This Micro AI can control several messengers at the same time, which can but do not have to move in a group. They can be put on the map altogether in one location, or be spread out on the map or across different turns.
* The farther a messenger has moved through the chain of waypoints, the higher a priority it is for the AI, meaning that farther advanced (on the map) messengers are moved first, and that the escort units try to clear the way and stay with those messengers more so than with those further back on the map. This order can be inverted using the invert_order= key.
* If several messengers are on the map, escort units might move from one to the other, the AI making a judgement call where they are needed most. Closeness to a messenger is generally the most important criterion, but not the only one.
* If a messenger dies, the escort units previously staying with it now join one of the other messengers if there are any left (otherwise they follow default AI behavior).
* If you want certain escort units to stay always with the same messenger, use several messenger [micro_ai] tags with different [filter]/[filter_second] combinations.

For a demonstration, check out the "Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Messenger Escort Micro AI by using
ai_type=messenger_escort
in the [micro_ai] tag.

===Messenger Escort specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': {{DevFeature1.13|0}} (Previous to 1.13.0, only id= was allowed.) The id of a unit or a [[StandardUnitFilter|Standard Unit Filter]] selecting the units controlled by this Micro AI.
** One or the other is required
** If both are given, [filter] takes priority over id=
** The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
* '''waypoint_x,waypoint_y''': Comma-separated list of waypoint coordinates through which the messenger will go in the given order to reach its goal, given by the last coordinate. If you want the messenger to go directly to the goal, simply enter a single x,y coordinate here. Note that the messenger does not have to hit each waypoint exactly (except for the final one), getting close to them is good enough. {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|11}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Note that the Messenger Escort AI consists of 3 CAs with scores ranging from <tt>ca_score-2</tt> to <tt>ca_score</tt>.
* '''enemy_death_chance'''=0.67 and '''messenger_death_chance'''=0.0: (both floats; ranging from 0 to 1) If the messenger is adjacent to an enemy at the end of the move, it will only attack the enemy if the chance of death of the enemy is >= enemy_death_chance and if the messenger's chance of death is <= messenger_death_chance (or if it is an attack at a range for which the enemy does not have a weapon).
* '''[filter_second]''': {{DevFeature1.13|0}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the escort units. If not set, this defaults to all enemy units. The filter automatically includes the side= key set to the AI side.
* '''invert_order'''=no: {{DevFeature1.13|0}} If set to 'yes', the order of priority with which messenger units are considered is inverted, starting with the messenger unit that is the least advanced on the map (see description above). In most cases, selecting this option results in worse performance of the AI, so use it with caution. (And obviously it has no effect at all if there is only one messenger controlled by the AI.)

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|11}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of [micro_ai] tag usage from the "Messenger Escort" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=messenger_escort
action=add

[filter]
id=messenger
[/filter]
waypoint_x=31,24,27,28
waypoint_y=20,14,7,1
[/micro_ai]

== Patrol Micro AI (ai_type=patrol) ==

The defines a number of waypoints for a unit (or units) to follow. Options can be set whether the route should be followed in a loop, as an out-and back, only once, whether units encountered along the way should be attacked, etc.

With the default settings, getting to the next waypoint takes priority over attacking for a patroller, but this can be overridden (as of '''Wesnoth 1.15.12''', using the '''attack_range''' option). Unless instructed otherwise, the AI thus prefers to move the patrol unit around enemies rather than straight for them. Also, if a waypoint is occupied by a unit the AI is not instructed to attack, it will (eventually) abandon that waypoint once it gets close enough and move on to the next one.

For a demonstration of several different patrol behaviors, check out the "Patrols" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Patrol Micro AI it by using
ai_type=patrol
in the [micro_ai] tag.

===Patrol specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|Standard Unit Filter]] selecting the units controlled by this Micro AI.
** One or the other is required
** If both are given, [filter] takes priority over id=
** The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
** If several units match the filter, the order in which they are controlled is not guaranteed. If the order matters, set up several MAIs using the id= key and different values for ca_score=.
* '''waypoint_x,waypoint_y''': Comma-separated lists of the waypoint coordinates through which the patrol travels (in order). {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''Optional keys:'''

* '''attack''': By default (if this key is not set), the patrol unit attacks any unit it ends up next to after a move, or that is within '''attack_range''' (see below). Alternatively, this parameter can be set to a comma-separated list of unit ids. If that is done, the patrol only attacks these units when it ends up next to them or if it gets within attack_range. It ignores any other unit. This can in turn be used to have the patroller not attack at all, by setting ''attack='' to a non-existing id. The exception to this is an enemy on the last waypoint with ''one_time_only=yes'', which will always be attacked.
* '''attack_range'''=1: {{DevFeature1.15|12}} If the patrol comes within this many hexes of an enemy unit, it interrupts its patrol route and attacks that enemy (assuming it still has enough movement left to get to the enemy). The '''attack=''' instructions are taken into account for this. Note that the patrol generally tries to move around enemies, which means that for the default value of 1, enemies are usually not within attack range, except at the end of the move.
* '''attack_invisible_enemies'''=no: {{DevFeature1.15|12}} If set to 'yes', the unit also attacks invisible enemies (according to the criteria set by '''attack''' and '''attack_range''').
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs.
* '''one_time_only'''=no: (boolean) If set to 'yes', the unit goes through the patrol route only once and then hangs out at the last waypoint. It also always attacks any enemy unit on the last waypoint, independent of what ''attack='' is set to.
* '''out_and_back'''=no: (boolean) By default, a patrol unit returns to the first waypoint after reaching the last, doing the patrol route as a loop. If this parameter is set to 'yes', the unit instead reverses its course and perpetually does out and backs of the route.

Here's an example of [micro_ai] tag usage from the "Patrols" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=patrol
action=add

[filter]
id=Konrad
[/filter]
waypoint_x=9,24,25
waypoint_y=21,23,15
one_time_only=yes
attack=Gertburt
[/micro_ai]

== Protect Unit Micro AI (ai_type=protect_unit) ==

The Protect Unit Micro AI tries to move one or several units to a given location while keeping them safe from enemy attacks. It does so by keeping the protected units away from enemy units and close to friendly units. Other units on the AI side are controlled by the default Wesnoth AI.

For a demonstration, check out the "Protect Unit" and "The Elves Besieged" scenarios from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Protect Unit Micro AI by using
ai_type=protect_unit
in the [micro_ai] tag.

===Protect Unit specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[unit]''': A separate [unit] tag is required for each protected unit(s). Each tag has required keys '''id''', '''goal_x''', '''goal_y''' for each unit, as shown in the example below. {{DevFeature1.15|0}} '''goal_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''disable_move_leader_to_keep'''=no: (boolean) If set to 'yes', side leaders protected by this AI do not try to return to their keep. This is necessary for this Micro AI to work with units that are side leaders and that are supposed to move to an off-keep location.

'''Notes:'''
*The Protect Unit Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|move leader to keep candidate action]].
* The CA evaluation scores of this AI are hard-coded. It does not work otherwise.

Here's an example of [micro_ai] tag usage from the "HttT: The Elves Besieged" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=protect_unit
action=add

[unit]
id=Delfador
goal_x,goal_y=1,2
[/unit]
[unit]
id=Konrad
goal_x,goal_y=1,1
[/unit]

disable_move_leader_to_keep=true
[/micro_ai]

== Recruiting Micro AI==
=== General Comments on the Recruiting Micro AIs ===

The Recruiting Micro AI replaces the default recruitment AI by alternative recruiting patterns. Currently there are two recruiting algorithms you can choose from, random recruiting and the rush recruiting used in the new (as of Version 1.11.1) Experimental AI (see below).

For a demonstration of a different recruiting pattern, check out the "Recruiting" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. You can also explore the unit choices by watching the Experimental AI in a multiplayer game.

'''Note:''' Obviously, the Recruitment Micro AI modifies the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|recruitment candidate action]].

=== Random Recruitment AI (ai_type=recruit_random) ===

This AI randomly selects a unit type from the recruitment list of the side. The probability of choosing each type and the behavior in low-gold situations can be influenced with optional parameters.

Enable the Random Recruiting Micro AI by using
ai_type=recruit_random
in the [micro_ai] tag.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''ca_score'''=180000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 180,000. This is identical to the default Recruiting CA which it replaces.
* '''[probability]''': This tag sets the probability of selecting the given unit type. It has two required sub-keys:
** '''type''': comma-separated list of unit types to which this probability is to be applied
** '''probability''': (non-negative float) The probability with which these unit types is to be selected. All unit types for which no [probability] tag is defined receive a default probability of 1.0, thus values should be chosen relative to that. As an example, in the code below swordsmen and peasants are given a probability of 8, while no other units have assigned probabilities. Thus, each of these two unit types is 8 times more likely to be selected than any other individual unit type.
* '''skip_low_gold_recruiting'''=no: (boolean) By default, the random recruitment AI chooses a unit to recruit only from those types for which it has sufficient gold. If this parameter is set to 'yes', it will instead choose from all available unit types and end recruiting for the turn if there is not enough gold to recruit it this turn (even if other, affordable unit types exist).

Here's an example of a random recruiting [micro_ai] tag usage from the "Recruiting" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=recruit_random
action=add

[probability]
type=Swordsman,Peasant
probability=8
[/probability]

skip_low_gold_recruiting=yes
[/micro_ai]

=== Rush Recruitment AI (ai_type=recruit_rushers) ===

This AI replaces the default recruiting with the recruiting used in the Experimental AI [[Experimental_AI#Recruitment|as described here]].

Enable the Rush Recruiting Micro AI by using
ai_type=recruit_rushers
in the [micro_ai] tag.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''ca_score'''=180000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 180,000. This is identical to the default Recruiting CA which it replaces.
* {{DevFeature1.15|2}} '''high_level_fraction'''=0: (non-negative number) The approximate fraction of units of level 2 or higher to be recruited. This is defined as fraction of units on the map, not of new units being recruited during a turn or over several turns (which makes a difference if there are already units on the map). The effect is also cumulative per level (starting from level 2), meaning that 1/3 of L2 units will be recruited in the example above, 1/3*1/3=1/9 L3s etc. The default value is zero, which leaves the high-level unit recruiting to the default Experimental AI algorithm resulting usually in very few such units being recruited.
* '''randomness'''=0.1: (number) A random number is applied to the rusher recruit engine's score to prevent the recruitment pattern from being too predictable. 0 causes no randomness to be applied, while larger numbers increase the random effect. A value of 1-2 generates results in which the random effect is approximately equal to the scored effect. Extremely high values are essentially entirely random.
* {{DevFeature1.17|6}} '''reset_cache_each_turn'''=no: (bool) Many of the operations of the rush recruitment evaluation are expensive and are therefore cached. For the most part, this cache can be kept from turn to turn, but in case there are events that change, for example, the map or the recruit list, this parameter can be set to 'yes' to force a reset of the cache each turn.

Here's an example of a rush recruiting [micro_ai] tag usage from the "Recruiting" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=recruit_rushers
action=add
[/micro_ai]

== Simple Attack Micro AI (ai_type=simple_attack) ==

The Simple Attack Micro AI is meant as an addition to the default combat candidate action for when one wants to force the AI to do attacks that it would otherwise not do (for example on units that are 1 XP from leveling) or to execute certain attacks before all others (for example, attack with all "expendable" units first). It is not set up to be a replacement for the default attacks. Some notes:

* The algorithm is different from and simpler than that of the default combat CA. For example, no attack combinations are considered, only individual attacks. As a result, the [[AiWML#List_of_AI_Aspects|default aspects]] (aggression, caution, [avoid], ...) are not taken into account. Also, if lots of units are involved, evaluation of this Micro AI is potentially quite a bit slower than of the default attacks.

* If an attack matching the Standard Unit Filters described below is found, this attack will always be executed, no matter how bad the odds are. Thus, this Micro AI can be used to force the AI to do attacks it would otherwise avoid.

* Other than selecting the attacker/defender units, this AI is currently not configurable. Let us know if you would like to see certain options to be added. (No guarantees that we will add them, but we will definitely consider them.)

For a demonstration, check out the "Simple Attack" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Simple Attack Micro AI by using
ai_type=simple_attack
in the [micro_ai] tag.

===Simple Attack specific keys for the [micro_ai] tag===

'''Required keys:'''

There are no required keys. It is, however, in general not desirable to use this AI without at least one of the optional Standard Unit Filters below, as this AI is not meant as a replacement of the default combat candidate action.

'''Optional keys:'''

* '''ca_score'''=110000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 110,000, which means that it is executed right before the default combat candidate action.
* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Simple Attack action. It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units the AI should attack. It defaults to all enemy units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.
* '''weapon'''=-1: (integer) The number of the weapon that should be used for this attack. Weapon numbers start at 1 (not 0). -1 stands for "best weapon" (by whatever criterion the AI chooses to use). '''Available from Wesnoth 1.11.8'''

Below are 2 examples of Simple Attack Micro AI configurations from the "Simple Attack" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. The first one shows how to force the AI to attack with all Soulless and Walking Corpse units first:
[micro_ai]
side=2
ai_type=simple_attack
action=add

ca_score=110000
[filter]
type=Soulless,Walking Corpse
[/filter]
[/micro_ai]

The second example executes attacks by Soulless on all enemy units that are 1 XP from leveling. Note that the Lua code in the preload event is there simply in order to code the "1 XP from advancing" condition. It is not needed for most other SUFs, as can be seen in the previous example.
[event]
name=preload
first_time_only=no
[lua]
code=<<
function close_to_advancing(unit)
if (unit.experience >= unit.max_experience-1) then
return true
else
return false
end
end
>>
[/lua]
[/event]

[event]
name=prestart
[micro_ai]
side=2
ai_type=simple_attack
action=add

ca_score=110001
[filter]
type=Soulless # No Walking Corpses; L0 units don't advance enemy
[/filter]
[filter_second]
lua_function = "close_to_advancing"
[/filter_second]
[/micro_ai]
[/event]
Several Simple Attack Micro AIs can be combined for the same AI side. The two examples above are both used (note the different values for ca_score) in the "Simple Attack" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

== Custom Micro AIs ==

{{DevFeature1.13|5}}

From 1.13.5 onwards, adding a new Micro AI can be easily done without altering any core files or overriding the micro_ai tag. The [micro_ai] tag now looks up its ''ai_type'' parameter in the <code>wesnoth.micro_ais</code> table and uses the micro AI setup function found there to determine which keys are required and allowed and what candidate actions to add.

A micro AI setup function takes as its single parameter the contents of the [micro_ai] tag and returns three separate values:
*'''required''': A list of required keys and tags, as strings. Tags are indicated by enclosing them within square brackets in the string. If a key or tag in this list is missing from the [micro_ai] tag, an error will be printed. {{DevFeature1.17|6}} In order to enable better error handling, the syntax of this table has been changed. It is now of format <syntaxhighlight lang='lua' inline>{ param1 = 'param1_type', ... }</syntaxhighlight>. The supported parameter types can be found at the link to examples below.
*'''optional''': Similar to above, a list of optional keys and tags, as strings. No error will be printed if a key or tag in this list is missing, nor will an error be printed if it is present (as would be the case for unrecognized keys or tags). {{DevFeature1.17|6}} The format of this table has been changed in the same way as for 'required'. Also, a warning message is now issued if the '[micro_ai]' tag contains a key or tag that is not listed in either 'required' or 'optional'.
*'''ca_params''': A table specifying the candidate actions that constitute the micro AI. It should contain an ''ai_id'' key (which specifies a base ID to be used for candidate actions of this micro AI) and a series of candidate action definitions. Each candidate action definition is a table containing the following keys:
**'''ca_id''': The ID used for the candidate action. This will be combined with the ''ai_id'' to produce the final ID.
**'''location''': Path to the Lua file that defines the candidate action.
**'''score''': The maximum score for the candidate action. If the [micro_ai] tag specified a ''ca_score'' parameter, the score here should normally be based on that.

(The return statement would thus look like <syntaxhighlight lang='lua' inline>return required, optional, ca_params</syntaxhighlight>.)

'''Examples''' of micro AI setup functions can be found in the [https://github.com/wesnoth/wesnoth/tree/1.14/data/ai/micro_ais/mai-defs default MAI definitions directory]. See the [https://github.com/wesnoth/wesnoth/blob/1.14/data/ai/micro_ais/mai-defs/animals.lua#L4-L12 Big Animals MAI definition] for a simple example. For custom micro AIs, the setup code should be put into a ''[lua]'' tag inside a preload event.

Since the function has full access to the contents of the [micro_ai] tag, it can conditionally add candidate actions to '''ca_params''' depending on the values of other keys within the [micro_ai] tag. It can also perform other actions such as adding facets to an aspect; if it does such things, it should pay attention to the ''action'' key to determine whether it's being added or removed.

There are two useful helper functions that can be used by Micro AI setup functions requiring aspect changes. They can be brought into scope by a line similar to the following:
<syntaxhighlight lang='lua>local MAIH = wesnoth.require("ai/micro_ais/micro_ai_helper.lua")</syntaxhighlight>
* MAIH.add_aspects(side, aspect_params)
* MAIH.delete_aspects(side, aspect_params)

The ''aspect_params'' parameter is an array of tables, each of which contains the following keys:
*'''aspect''': The aspect to change.
*'''facet''': The WML defining the facet. This must include an ''id'' key in order for the aspect to be correctly deleted. For maximum compatibility, incorporate the ''ca_id'' key from the [micro_ai] tag.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

Micro AIs

2023-08-16T15:33:36Z

Name:

== A Few General Words about Micro AIs ==

* Micro AIs allow Wesnoth campaign and scenario authors to add new AI functionality without the need for any AI programming. They bring new specialized behavior to Wesnoth that cannot be achieved, at least not easily, by adjusting default AI parameters (such as those described at [[AiWML]]) or with WML code.

* A Micro AI is activated and configured (or deleted) via the [micro_ai] tag placed in an event, requiring only a few lines of WML code. {{DevFeature1.15|?}} Starting in 1.16 the [micro_ai] tag may also be used in [side][ai] or [unit][ai]. These are both shorthands for placing it in the prestart event with "action=add", side set to the side, and in the case of [unit][ai], a [filter] tag set to limit the Micro AI to that one unit.

* '''Before Wesnoth 1.13.6''', the Micro AI behavior was inconsistent when it came to '''hidden enemies and petrified units'''. Some Micro AIs ignored those, while others did not. In some case there was even a potential for AI errors when an AI unit ran into hidden or petrified enemies. As of 1.13.6, this has all been fixed. The Micro AIs now correctly and consistently ignore hidden units and treat petrified units as blocking the hex they are on but having no effect otherwise, in the same way as the default AI does. '''Important notes:'''
** It is not possible to re-include hidden/petrified units via the Standard Unit Filters (SUFs) used by some of the Micro AIs. In fact, if this is attempted, the filters will generally not match any unit.
*** This only applies to SUFs which go directly into the [micro_ai] tag. Any SUF that is a sub-tag of another filter (for example, of a Standard Location Filter) is taken literally and returns all units matching the filter. If hidden or petrified units are to be excluded from such a sub-filter, that needs to be specified directly in that filter.
** We also note that, because all the Micro AIs are written in Lua, it is possible to [[Micro_AIs#Using_Development_.281.13.29_Version_Micro_AIs_in_your_Stable_.281.12.29_Version_Add-on|move a Micro AI's code into one's add-on]] and modify it to whatever scenario-specific behavior is desired (this does not only apply to hidden/petrified units, but to all behavior). Setting up general Micro AI behavior that works in every possible setting is not feasible, but adapting it to work (only) in the specific setting of a given scenario is often quite simple. If you do not know how to do this, please post a message on the Wesnoth forums and we will be happy to help you with it.

* The '''[[AiWML#List_of_AI_Aspects|default AI aspects]] are, for the most part, not taken into account by the Micro AIs'''. For example, unless noted otherwise, specifying a value for ''aggression'' does not change the MAI behavior. The exception is the ''[avoid]'' tag which is taken into account by many Micro AIs (except those for which it would interfere with the Micro AI behavior or those that already use a a [[StandardLocationFilter|Standard Location Filter]] that can be used for the same purpose). This is a feature of the Micro AIs, not a bug. If you feel that a certain default AI aspect should also apply to a Micro AI, please let us know in the [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 Micro AIs Feedback thread].

* '''Before Wesnoth 1.13.7''', the Micro AIs did not all work reliably when the '''AI side is under shroud''' and it may have been necessary to turn shroud off for the side when using a Micro AI. {{DevFeature1.13|7}} The Micro AIs now all work for sides under shroud. They do this by disregarding shroud for terrain purposes when path finding, consistent with default Wesnoth AI behavior, while still ignoring hidden units (including those hidden under shroud) correctly.

* Most Micro AIs in their default setting apply to all units of a side, although many of them provide parameters for filtering the units that should be affected by the new behavior. If the Micro AI is applied only to part of the units of a side, the other units follow the default Wesnoth AI behavior.

* Micro AIs are available in mainline since Wesnoth 1.11/1.12.

== Micro AI Test and Demo Scenarios ==

All Micro AIs described here can be checked out in a number of test and demo scenarios. The easiest way to access the test scenarios is by assigning a hotkey to "Start Test Scenario" in the preferences (as of Wesnoth 1.13.8). Then, simply press the hotkey in the titlescreen and select the desired scenario from the list (e.g. 'micro_ai_test' for the overall "switchboard scenario").

Test scenarios can also be accessed from the command line by typing
path/wesnoth-executable -t micro_ai_test
or (depending on your system and Wesnoth version)
path/wesnoth-executable -tmicro_ai_test
This starts up a "switchboard scenario" in which you can select the Micro AI demonstration scenario you want to check out. Here, ''path/wesnoth-executable'' needs to be replaced by whatever the path and filename of the Wesnoth executable is on your system.

== Setting up a Micro AI ==

Setting up a Micro AI requires only one simple step:
==== Activating and configuring (or deleting) a Micro AI ====

Micro AIs are activated, deleted and configured using the [micro_ai] tag. This tag needs to be placed in [[ActionWML]], that is, in an event, a menu option or the like. As an example, the following code activates the healer_support Micro AI in its default configuration for Side 2 from the beginning of the scenario:
[event]
name=prestart

# Configure the healer support micro AI
[micro_ai]
side=2
ai_type=healer_support
action=add
[/micro_ai]
[/event]
'''Keys required for all Micro AIs:'''
All [micro_ai] tags must contain the following three required keys:
* '''side''': The side for which the Micro AI is to be added, changed or deleted. As of version 1.17.0 this can be a list of sides.
* '''ai_type''': The type of Micro AI to be added, changed or deleted. See the following sections for allowed values.
* '''action''' (string): The action to take concerning the Micro AI. The following values are allowed:
** ''add'': Add a Micro AI to a side.
** ''change'': Change the configuration of an existing Micro AI. Note that this does not only change the specific parameters provided in the tag, but it replaces the entire existing Micro AI by a new version with the new (and only the new) configuration. It is therefore equivalent to using first the ''delete'' and then the ''add'' action.
** ''delete'': Delete an existing Micro AI from a side.

'''Keys required under certain circumstances:'''
* '''ca_id''': (string) If several MAIs of the same type are used for the same side and one or several of these are to be changed or deleted during a scenario, this key needs to be included so that the [micro_ai] tag knows which of them needs to be changed/deleted. The same is also true if a Micro AI is changed more than once during a scenario. We therefore '''strongly recommend always setting ''ca_id''''' for MAIs which are, or might be, changed or deleted during a scenario.
** '''Note:''' The id(s)/name(s) actually assigned to the CA(s) of the MAI by the engine might be different from the parameter passed here. It is, however, sufficient to use this ca_id with the [micro_ai] tag add/delete/change actions to identify the MAI uniquely. (In other words: you don't have to worry about this if you always use the [micro_ai] tag, but might have to figure out the actual name(s) of the CA(s) if you want to delete or change them manually.)
* Other keys may also be required depending on the Micro AI. In additional, a number of optional keys may be available to configure the AI behavior. See the sections on the individual Micro AIs for details.

'''Required keys for deleting a Micro AI:'''

Only a subset of the keys required for setting up a Micro AI are needed when deleting it. '''side''', '''ai_type''' and '''action'''=delete always need to be provided. '''ca_id''' needs to be given if it was provided when adding the Micro AI (see above for when this is needed).

'''Notes:'''
* The ''add'' and ''change'' actions ignore all keys that do not apply to the respective Micro AI type. The ''delete'' action ignores all keys other than the required keys listed above.

* Some of the Micro AIs use and/or modify default AI components (candidate actions or aspects) when they are added, or reset these components to their default values when they are deleted. Thus, if you have modified the AI yourself using the default CAs or aspects, some of these modifications might be affected, or might be interfering with the Micro AI. The sections below indicate whether a Micro AI modifies any default AI components.

===Combining Different Micro AI Types for the Same Side===

No extra steps need to be taken when combining different Micro AIs on the same side. Simply set up the [micro_ai] tags for all AIs you want to use.

'''Notes:'''
* While it is ''technically'' possible to combine any number of Micro AIs, this does not mean that all Micro AIs work together in practice. Some are not compatible because they control units in contradictory ways.
* Not all combinations that ''should'' work have been tested yet. If you find a combination that you believe should work but doesn't, [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 please let us know] and we will see if that can be fixed.
* The candidate action score almost certainly has to be set (using the ca_score= key) for one or several of the MAIs if several of them are used on the same side.

== Animals Micro AIs ==
=== General Comments on the Animal Micro AIs ===

The Animals Micro AIs are meant to simulate the behaviors of certain types of animals. They are, however, set up so that they can be used with arbitrary unit types and might be applicable in quite diverse situations. The AIs nevertheless remain named after the animals for which they were written originally, so that they are (to some extent) descriptive of their behavior.

Brief descriptions of the AI behaviors are given in the following subsections. To get a better feeling for their behavior, check out the "Animals", "Swarm", "Wolves" and "Dragon" scenarios from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. Note that some of the animal AIs are designed for animal types that do not exist in mainline. In the test scenario, other animal types are therefore substituted for them.

=== Animals AI: Wolves (ai_type=wolves) ===

The Wolves Micro AI organizes all "wolf" units (predators) of the side to hunt in a single pack. They actively chase after the closest prey and try to corner it (not always super successfully), but are easily distracted by other enemy units coming into attack range, to the point where the pack might split up. The wolves can, however, be told to attack only prey units as well as to try to avoid other types of units (such as larger predators). When no prey is left, the wolves wander randomly.

This AI works best for a small number of predators (2 - 5) and sparse prey. Also, the predators should be put on the map in a pack, that is, reasonably close to each other. For a demonstration of the Wolves AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Note that another wolves AI exists, called [[Micro_AIs#Animals_AI:_Multi-pack_Wolves_.28ai_type.3Dwolves_multipacks.29|Multipack Wolves]], which distributes the wolves of a side into several packs, rather than all of them into one single pack as it is done here.

Enable the Wolves Micro AI by using
ai_type=wolves
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the predator units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the prey units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''attack_only_prey'''=no: In the default configuration, the wolves attack all enemy units in attack range. If this key is set to 'yes', they only attack prey units.
* '''avoid_type''': Comma-separated list of unit types (on enemy sides) which the wolves try to avoid. They try to stay out of these units' way as much as possible when moving around (except when they are moving in to attack another enemy unit) and never attack them.
* '''ca_score'''=90000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 90,000, which is lower than the default combat CA, but higher than most other default CAs which move units. It can be changed by setting this parameter but in most cases this will not make sense. Note that the Wolves AI consists of 2 CAs with scores ranging from <tt>ca_score-1</tt> to <tt>ca_score</tt>.

'''Notes on default (RCA) AI aspects:'''
* If ''attack_only_prey'' or ''avoid_type'' are set, the Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]].
* Attacks by the wolves are left to the default (RCA) AI, meaning that the value of ''aggression'' has an influence on the behavior.
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI is taken into account. Note: as attacks by the wolves are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

Here's an example of a wolves [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=6
ai_type=wolves
action=add

[filter]
type=Wolf
[/filter]
[filter_second]
type=Vampire Bat
[/filter_second]
avoid_type=Yeti,Giant Spider,Ghast,Footpad
[/micro_ai]

=== Animals AI: Multi-pack Wolves (ai_type=wolves_multipacks) ===

The Multi-pack Wolves Micro AI is different from the [[Micro_AIs#Animals_AI:_Wolves_.28ai_type.3Dwolves.29|Wolves Micro AI]] in that there can be an arbitrary number of wolf packs, with the pack size being a free parameter. At the beginning of the scenario, close wolves are grouped into packs in a semi-methodical way. If the wolves are put on the map in distinct groups of close wolves of the correct number, they will be joined into packs matching these groups. If, on the other hand, they are spread out all over the map, the method of assigning them to packs is semi-random.

Wolves of the same pack begin by joining each other on the map. After that, they stay together until only one wolf is left, which then tries to join up with an incomplete pack or with other single wolves. Individual wolves entering the map during the scenario behave in that way as well.

A second difference to the other Wolves AI is that wolves do not actively hunt here. For the most part they just wander (often long distance). However, the pack ferociously (and without regard for its own health) attacks any enemy units that come into range, as long as that does not mean separating the pack by more than a few hexes. Staying together, or joining with a new wolf assigned to the pack, is the only thing that takes priority over satisfying the wolves' thirst for blood.

For a demonstration of the Multi-pack Wolves AI behavior, check out the "Wolves" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Multi-pack Wolves Micro AI by using
ai_type=wolves_multipacks
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

There are no required keys

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Note that the Multi-pack Wolves AI consists of 2 CAs with scores ranging from <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''pack_size'''=3: (integer) The size of the packs.
* '''show_pack_number'''=no: If set to "yes", the wolves' pack numbers will be shown below them. Note that this means that the pack number of a wolf killed in an attack will remain as a label on the map. This behavior is intentional to help UMC authors note where units might have made suicidal mistakes.
* '''type'''=Wolf: Comma-separated list of the unit types which the AI controls. The default value is "Wolf".

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a wolves_multipacks [micro_ai] tag usage from the "Wolves" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=wolves_multipacks
action=add

show_pack_number=yes
pack_size=4
[/micro_ai]

=== Animals AI: Big Animals (ai_type=big_animals) ===

The Big Animals Micro AI is a simulation of large predators that wander and hunt alone, such as Bears, Giant Spiders or Yetis. For the most part, these just wander on the terrain that's been defined for them, but they attack enemy units if those happen to come into range. The AI can be set up so that the Big Animals stay out of the way of other units (such as other large predators), in which case they only attack those if cornered or if they run into them accidentally (such as ambushers).

For a demonstration of the Big Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Big Animals Micro AI by using
ai_type=big_animals
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the animals to which this AI is applied. The filter automatically includes the side= key set to the AI side.

'''Optional keys:'''

* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs.
* '''[filter_location]''': The big animals often go for long distance (multi-turn) journeys. This tag is a [[StandardLocationFilter|Standard Location Filter]] describing the terrain from which the next goal is chosen. The default is all terrain on the map.
* '''[filter_location_wander]''': The terrain on which the big animals will end their moves. This is a [[StandardLocationFilter|Standard Location Filter]]. The default is all terrain on the map.
* '''[avoid_unit]''': A [[StandardUnitFilter|Standard Unit Filter]] describing all enemy units that the big animals will avoid. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

Here's an example of big_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=3
ai_type=big_animals
action=add

[filter]
type=Ghast
[/filter]
[avoid_unit]
type=Yeti,Giant Spider,Ghast,Footpad
[/avoid_unit]
[filter_location]
x,y=1-40,1-18
[/filter_location]
[/micro_ai]

=== Animals AI: Forest Animals (ai_type=forest_animals) ===

The Forest Animals Micro AI simulates a number of different animal behaviors that one might find in a forest, namely animals behaving like deer, rabbits and families of tuskers. In the following, we will refer to those animals by these types, even though the actual unit types can be selected freely. They behave as follows:
* Each deer wanders randomly on (selectable) terrain, except when enemies get in its (the deer's) maximum movement range, in which case it flees to the farthest point it can reach.
* Tuskers exhibit the same behavior as deer, except when an enemy is next to one of the tusklets. This enemy is attacked unconditionally by the tuskers trying to protect their young.
* Tusklets blindly follow the closest adult tusker, except when there is no tusker left, in which case they behave the same as deer.
* Rabbits also wander randomly, but in addition disappear into their holes (if any are within reach) when enemies are close. They reappear out of their holes at the beginning of the turn, if it is safe.

For a demonstration of the Forest Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Forest Animals Micro AI by using
ai_type=forest_animals
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

There are no required keys

'''Optional keys:'''

* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Note that the Forest Animals AI consists of 4 CAs with scores ranging from <tt>ca_score-3</tt> to <tt>ca_score</tt>.
* '''rabbit_type, tusker_type, tusklet_type, deer_type''': Comma-separated lists of the unit types behaving as the respective animals. If any of these parameters are not set, those types of animal behavior are skipped by the AI.
* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the terrain on which the forest animals wander when they are not threatened by enemies.
* '''rabbit_number'''=6: (integer) The number of rabbits for the AI to have on the map simultaneously. The AI puts the missing number of rabbits onto the map at the beginning of the AI's turn (when the rabbits come out of their holes).
* '''rabbit_enemy_distance'''=3: (number) Rabbits won't spawn in holes that aren't more than this distance away from all enemies.
* '''rabbit_hole_img''': Rabbit holes are marked by items on the map. If this parameter is set, it must be the file name of the item image. If it is not set, all items on the map are treated as rabbit holes.
** {{DevFeature1.14|10}} Items used for rabbit holes on the map border used to produce an error. Placing them on the map border therefore needed to be avoided on the scenario setup side. They are now automatically excluded from consideration by the AI code.

Here's an example of forest_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=forest_animals
action=add

deer_type=Vampire Bat
rabbit_type=Giant Rat
tusker_type=Ogre
tusklet_type=Young Ogre
[filter_location]
terrain=*^F*
[/filter_location]
[/micro_ai]

=== Animals AI: Herd and Herders (ai_type=herding) ===

The Herding Micro AI sets up an area on the map where a number of herder units (such as sheep dog) control and protect a herd (such as sheep). For convenience, we simply refer to them as sheep dogs and sheep in the following, even though arbitrary unit types can be selected for either.

Sheep dogs try to keep their sheep safe. This involves keeping them inside the herding area, positioning themselves in between the sheep and approaching enemies, and attacking the enemies if those get too close. If no active herding or protecting move is needed, the dogs go to a random location on the perimeter of the herding area.

Sheep wander aimlessly except when a sheep dog is next to them, in which case they run away from the dog. The dogs exploit this by positioning themselves on the outside of the sheep, if possible. Sheep also run away from approaching enemies.

For a demonstration of the Herding AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Herding Micro AI by using
ai_type=herding
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] describing the herder units (e.g. dogs). The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] describing the herd units (e.g. sheep). The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the terrain forming the perimeter of the herding area. In other words, this is the path the herders (dogs) use to patrol around the outside of the herding area. This must be a set of coordinates ''completely enclosing'' the herding area. Here's an example of setting up a rectangular perimeter:
[filter_location]
x=10-20,10-20,10, ,20
y=11, 21, 11-21,11-21
[/filter_location]
Another possibility is by defining the path by certain terrain on the map (as it is done in the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]), in which case the filter can simply look like this:
[filter_location]
terrain=Rb
[/filter_location]
* '''herd_x,herd_y''': The coordinate of one hex (''any'' one hex) inside the herding area. This is needed to define which part of the map is on the ''inside'' of the herding area perimeter defined by [herding_perimeter], and which is the ''outside''. {{DevFeature1.15|0}} '''herd_loc''' can be used instead with a named/special location.

'''Optional keys:'''
* '''attention_distance'''=8: (integer) If an enemy is within this distance of a herd unit, but not as close as ''attack_distance'', the herders try to position themselves in between the enemy and the herd unit.
* '''attack_distance'''=4: (integer) If an enemy is within this distance of a herd animal, the herders attack this enemy.
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Note that the Herding AI consists of 6 CAs with scores ranging from <tt>ca_score-5</tt> to <tt>ca_score</tt>.

Here's an example of a Herding [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=7
ai_type=herding
action=add

[filter]
type=Footpad
[/filter]
[filter_second]
type=Troll Whelp
[/filter_second]
herd_x,herd_y=32,28
[filter_location]
terrain=Rb
[/filter_location]
[/micro_ai]

=== Animals AI: Hunter (ai_type=hunter) ===

The Hunter Micro AI leads a unit (or units) through hunt-and-rest cycles. The units wander in a prescribed area of the map, their hunting ground, until an enemy unit comes within range. Note that the units do not actively chase down enemies, but wander randomly through the hunting ground until an enemy is encountered.

If enemies are within range of a hunter unit, the hunter attacks the weakest of them. If a kill is made, it then retreats to its rest location, where it stays for a certain number of turns and until fully healed (whatever happens later).

A few more details:
* If the hunter's way home is entirely blocked on the return (so that there is no possible path), the normal RCA AI takes over its behavior.
* However, if the way is blocked by an enemy unit occupying the rest hex, that enemy will be attacked unconditionally.
* A kill only makes the hunter go home when it is the attacker, not as defender.

For a demonstration of the Hunter AI behavior, check out the "Dragon" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Hunter Micro AI by using
ai_type=hunter
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|Standard Unit Filter]] selecting the units controlled by this Micro AI.
** One or the other is required
** If both are given, [filter] takes priority over id=
** The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
** If several units match the filter, the order in which they are controlled is not guaranteed. If the order matters, set up several MAIs using the id= key and different values for ca_score=.
* '''home_x,home_y''': The coordinates of the hex to which the hunter returns and rests at after a kill. {{DevFeature1.15|0}} '''home_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs.
* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the unit's hunting ground. If this tag is not provided, the hunter uses all of the map.
* '''rest_turns'''=3: (integer) The number of turns the AI stays at home_x,home_y after a kill. It will not leave its home until this number of turns have passed ''and'' it is fully healed.
* '''show_messages'''=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase. Note that this is meant as debug output for the scenario author. The messages are not translated and are not included in replays (and are only visible to the host in an MP game).

Here's an example of a hunter [micro_ai] tag usage from the "Dragon" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=hunter
action=add

[filter]
id=Rowck
[/filter]
[filter_location]
x,y=5-30,1-15
[/filter_location]
home_x,home_y=3,15
rest_turns=2

show_messages=yes
[/micro_ai]

=== Animals AI: Swarm (ai_type=swarm) ===

The Swarm Micro AI uses some very simply algorithms to simulate animal swarm behavior. Without adjacent enemies, they simply do a random move, trying to stay together and at a certain distance from enemies. However, if an enemy unit is close to any bat, the swarm scatters. This is particular fun to watch when one places an enemy unit in the middle of the swarm. After being scattered, the swarm members slowly rejoin, but not in a very organized way. Sub-swarms or individual bats might roam around for quite some time before they find their way back. It is also possible that individual bats (or small groups) split off from the larger swarm at times.

For a demonstration of the Swarm AI behavior, check out the "Swarm" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Swarm Micro AI by using
ai_type=swarm
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

There are no required keys

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Note that the Swarm AI consists of 2 CAs with scores ranging from <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''enemy_distance'''=5: (int) The minimum distance kept between units of the swarm and enemies when the swarm moves as a whole.
* '''[filter]''': {{DevFeature1.15|12}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the swarm. The filter automatically includes the side= key set to the AI side.
* '''scatter_distance'''=3: (int) Enemies within "scatter_distance" hexes of any swarm unit cause the swarm to scatter, by each unit trying to maximize its individual distance from the enemy.
* '''vision_distance'''=12: (int) Only units within this distance follow the overall swarm motion (either away from an enemy or of the swarm as a whole). The smaller this value is set, the less likely the swarm is to stay together or rejoin. This parameter is meant to simulate how far an individual member of the swarm can see, meaning that the swarm is "out of sight" (and the unit will not be able to follow it) if it is more than this distance away.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a Swarm [micro_ai] tag usage from the "Swarm" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=swarm
action=add
[/micro_ai]

== Assassin Squad Micro AI (ai_type=assassin) ==

{{DevFeature1.13|6}}

This Micro AI controls one or several assassin units which try to circle around enemy units with the goal of hitting a target unit without being distracted or impeded by other enemies. The units will always attack the target if such attacks are possible, otherwise they will follow the path of least resistance toward it. Notes:

* The main priority for the AI is to find paths that avoid enemy units. However, if no such path can be found, the assassins will still advance toward the target, taking the path exposing the units to the least potential damage from enemies.

* The units will not necessarily follow the same path. The best path is chosen individually for each unit.

* While it is not a requirement for the AI to work, using ambusher or skirmisher units, or units with the quick trait, makes this AI more lethal in many cases.

* The CA evaluation scores of this AI are hard-coded, it does not work otherwise. That means that '''ca_score''' is not a valid key for the [micro_ai] tag.

Enable the Assassin Squad Micro AI by using
ai_type=assassin
in the [micro_ai] tag.

===Assassin Squad specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the assassin units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the target unit.
** It is important to realize that the AI currently only works correctly with a single target unit. It is thus the responsibility of the scenario designer to make sure that this filter matches an individual enemy unit. If several enemy units are to be targeted in the same scenario, several instances of the Assassin Micro AI can be used.
** The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''[prefer]''': A [[StandardLocationFilter|Standard Location Filter]] selecting locations on the map for the assassins to prefer when making their way toward the target unit. This could be used, for example, to make units with the ambush ability move (mostly) through forest or to have the assassins circle around the, say, northern part of the map rather than the south if that is desirable for scenario design purposes.
** As with avoiding enemies, the units will still move across non-preferred terrain if that is either the only option or ''much'' shorter than preferred terrain
** Attacking, once the target unit is in range, is not influenced by the [prefer] SLF.

Here is an example of an Assassin Squad [micro_ai] tag usage:
[micro_ai]
side=2
ai_type=assassin
action=add

[filter]
type=Assassin,Master at Arms,Duelist
[/filter]
[filter_second]
id=Konrad
[/filter_second]
[prefer] # Circle around northern part of map
x=1-9, 10-99
y=1-37, 1-17
[/prefer]
[/micro_ai]

== Bottleneck Defense Micro AI (ai_type=bottleneck_defense) ==

The Bottleneck Defense Micro AI lets you define a location on the map where the AI can take a defensive stance behind a narrow passage (bottleneck). Units on the front line are backed up by healers and/or units with the leadership ability. Injured units are moved to the back and replaced by uninjured (or less injured) units. The units on the front line only attack when it is safe (no retaliation) or when there is a high chance that they will make a kill or level up. Using this Micro AI only makes sense if there is no way for the enemy sides to move around the bottleneck and attack the AI's units from behind.

For a demonstration, check out the "Bottleneck" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Bottleneck Defense Micro AI by using
ai_type=bottleneck_defense
in the [micro_ai] tag.

===Bottleneck Defense specific keys for the [micro_ai] tag:===

'''Required keys:'''

The Bottleneck Defense AI requires two sets of coordinates that define where it should be taking up its defensive stance, and from which side the enemy attacks at that location.

* '''x,y''': Comma separated lists of the hexes on the front line, where strong units are placed. All hexes on which the AI makes contact with (can be attacked by) the enemy need to be included here. Units are placed on them in the order in which they are listed here. {{DevFeature1.15|0}} '''location_id''' can be used instead with named/special locations.
* '''enemy_x,enemy_y''': Comma separated list of the hexes from which the enemy can attack the AI front line units. This is needed for the AI to know on which side of the front line support units (healers etc.) need to be placed. In many cases, it is sufficient to provide only one of the enemy front line hexes, but there are geometries for which that does not work. It is therefore safer to list all enemy front line hexes here. {{DevFeature1.15|0}} '''enemy_loc''' can be used instead with named/special locations.

'''Optional keys:'''

By default, the AI places healers and units with the leadership ability both on the front line itself (if they are the strongest units available) and on hexes adjacent to and behind the line. If different placement is desired, these locations can be overridden with the following keys.

* '''active_side_leader'''=no: (boolean) If set to 'yes', the side leader participates in the bottleneck defense action after the side's gold has been spent. If set to 'no' (default), the leader follows default AI behavior (sitting on the keep and recruiting, for the most part).
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Note that the Bottleneck Defense AI consists of 2 CAs with scores ranging from <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''[filter]''': {{DevFeature1.15|3}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the bottleneck defense. The filter automatically includes the side= key set to the AI side.
* '''healer_x,healer_y''': Comma separated list of hexes where healers are placed. This can be used to keep healers from the front line (or to take up only certain positions on the front line), and/or to override the default healing positions behind the line. Healers are placed on them in the order in which the hexes are listed, with the exception that hexes on the line always take priority over hexes behind the line. {{DevFeature1.15|0}} '''healer_loc''' can be used instead with named/special locations.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability. {{DevFeature1.15|0}} '''leadership_loc''' can be used instead with named/special locations.

As an example, in the "Bottleneck" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]], there are three front line hexes, two of which are on hill terrain, while the third is a road with a lower defense rating. The healer and side leader are supposed to participate in combat because they are strong units, but only from the hill hexes to keep them safer. This is accomplished by using the following keys settings (check out the scenario to see which hex is which):
[micro_ai]
side=1
ai_type=bottleneck_defense
action=add

x=14,14,14
y= 7, 9, 8
enemy_x=13,13
enemy_y= 8, 9

healer_x=14,14,15,15
healer_y= 7, 9, 8, 9
leadership_x=14,14,15,15
leadership_y= 7, 9, 9 ,8
active_side_leader=yes
[/micro_ai]

== Fast Micro AI (ai_type=fast_ai) ==

{{DevFeature1.13|0}}

This AI is meant as a fall-back AI for scenarios where there are so many units that attacks and moves done by the default AI are slow with long delays before each move. It replaces the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions (CAs). It should be obvious that in order to achieve the faster speed, compromises concerning the quality of the moves have to be made.

Enable the Fast Micro AI by using
ai_type=fast_ai
in the [micro_ai] tag.

'''Combat candidate action:'''
* Attackers are considered individually one at a time. The best attack found for a unit is executed without checking whether a better attack by another unit might be possible.
* The default order in which attackers are considered is by decreasing hitpoints, starting with the strongest unit (in terms of HP). This can be modified with the optional keys below.
* By default, if weaker units block attack hexes for a stronger unit, they do not move out of the way (this is the same as for the default AI). If a hex becomes available after an attack (e.g. due to a weaker unit dying in the attack), all attacks that were possible ''before'' this happened are finished first. Only after that are attacks by the stronger unit reconsidered.
* If include_occupied_attack_hexes=yes is set, weaker units move out of the way for stronger units if possible. This can, however slow down the AI depending on the situation on the map. Use with caution.
* {{DevFeature1.13|2}} Previous to this version, attacks by the leader were bunched in with the attacks by the other units. Now leader attacks are treated separately and contain an extra layer of analysis to determine whether the attack position is "safe" (in an approximate way). Currently, this is done with two simple considerations:
** Count all enemy units that can reach the leader's attack position. If there are more than given by optional parameter 'leader_attack_max_units' (default value 3), do not attack.
** Add up the hitpoints of all enemies that can reach the leader's attack position. If this value, multiplied by optional parameter 'leader_weight'(default value 2), is larger than the leaders hitpoints, do not attack.
** Two optional parameters, 'threatened_leader_fights' and 'leader_additional_threat', can also be used to let the leader attack when the threat at the attack hex is comparable to that at the leader's current position.
** In order to keep this AI as fast as possible, leader attacks are done by a separate candidate action that is only evaluated when all other CAs are done.

'''Move-to-targets, villages and retreat candidate actions:'''
* The move-to-targets, villages and retreat candidate actions of the default AI are removed. Move-to-targets and villages are taken over by the Fast Micro AI, whereas retreat is simply not done.
* This CA moves units toward goals after attacks are done. Goals are unowned (if the AI side has a leader only) and enemy-owned villages and enemy leaders.
* For each goal, units are pre-sorted in order of the fewest moves needed to cover the ''distance'' toward the goal (that is, as if move cost on each hex toward the goal were 1). Units are then considered sequentially and if a unit can get there "efficiently", its move is executed without considering other units.
** A move is considered efficient if the move cost to get to the hex is not more than 'move_cost_factor' larger than the distance to the hex. 'move_cost_factor' is an optional key that defaults to 2. It can be set to values of 1.1 or larger (see below).
** If the move for the current unit is not found to be efficient, the AI considers the next unit instead. If no unit can do an efficient move toward the goal, the best (fastest) of the inefficient moves is selected instead.

* Village goals:
** Village goals are considered before enemy leader goals so that the AI preferentially chooses scouts (or otherwise fast units) for them.
** The number of units sent toward villages depends on the value of the default AI aspect village_value. It is set to village_value/4 times the number of units the AI has left to move. Thus, by default (village_value=1.0) the AI sends a quarter of its units toward villages, and the rest toward enemy leaders. This means that the meaningful range of values for village_value is 0..4.
** Only one unit is moved toward each village. This consideration also overrides the number of units to move toward villages defined by village_value, topping it at the number of unowned/enemy-owned villages on the map.
** Setting village_value=0 disables moving units toward villages altogether. That is, not only are no units chosen, but the village targeting phase of the AI is entirely disabled with no evaluation time used for it. Note that, unlike with the default AI, this also means that no villages within range of an AI unit are grabbed.
** The order in which villages are chosen as goals is some combination of them being close to the AI side's leader and being spread out over the map.

* Enemy leader goals:
** The order of enemy leaders goals is set according to their distance from the AI leader with the closest enemy leader being targeted first (if the AI has a leader, otherwise their order is random). One unit is sent toward each enemy leader in this order, after which the AI starts with the first enemy leader again. This is repeated until all units have moved.

* Guardians (units with ai_special=guardian set) are ignored by the fast move-to-targets CA.

'''Tips for speeding up/modifying the Fast Micro AI in specific scenarios:'''

A number of optional keys and default AI aspects can be used to modify the behavior of the Fast Micro AI. The MAI is set up so that it is a reasonable compromise between speed and quality of the moves in most situations. However, this might not be ideal for all scenarios here are some things that can be done to speed up the AI (or to get better behavior in some situations by doing the opposite):
* Use large values for the default AI aspect aggression. The largest delays before attacks happen (in some circumstances) when the Fast MAI has to consider lots of units with attacks left but decides not to attack with them. See below for a description of how aggression is used by the fast AI.
* Use large values of move_cost_factor (see above for description of what this does). If you want to emphasize units that can move across terrain easily (e.g. bats) to be chosen for village grabbing, you might want to use low values of move_cost_factor, but this might slow down the AI. The default value should work reasonably well in most standard situations, but modifying the value might work better on specific maps.
* Don't use dungeon_mode=yes unless absolutely necessary, even in most dungeon crawls. Test the AI without this setting first and only use it if it is the only way to solve the problem. Often, a minor tweak to the map will have the same effect, without the speed penalty.
* Use include_occupied_attack_hexes=yes with caution. It might (or might not) slow down the attack CA significantly, depending on the scenario.
* Set village_value=0, which makes the AI not consider villages as goals. This has not been found to make a large difference on the maps tested so far, but it might have an effect on maps with a very large number of villages.
* Use attack_hidden_enemies=yes on maps where there are no hidden enemies. Excluding hidden enemies from the attack calculation requires an additional filter to be evaluated that takes extra time. In most cases this will not result in a large computation time saving.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''attack_hidden_enemies'''=no: (boolean) By default, hidden enemies are excluded from the attack calculation. Setting this to 'yes' makes the AI also consider those enemies as attack targets.
* '''[avoid]''': {{DevFeature1.13|2}} A [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). As with the default AI, units will not step on hexes defined by the [avoid] tag. In addition, no goals will be chosen that lie on those hexes. The one minor exception is that a unit stepping out of the way for another unit might temporarily enter the avoided zone.
* '''dungeon_mode'''=no: (boolean) As much as possible, the Fast Micro AI works with distances between hexes rather than path finding. This works pretty well on open maps and even most dungeon crawls (and similar scenarios), but it might result in some units getting temporarily (and in rare cases permanently) stuck on maps with convoluted labyrinths. If that is the case, setting dungeon_mode=yes triggers more path finding that avoids such situations (but as a result is somewhat slower).
* '''include_occupied_attack_hexes'''=no: (boolean) If set to 'yes', the AI moves weaker units out of the way for a stronger attacker. This might lead to better attacks but is slower, so don't use if speed is essential.
* '''[filter]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the attackers. Only AI units matching this filter will attack, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes the side= key set to the AI side. It does not affect the move-to-targets CA.
* '''[filter_second]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the enemies. Only enemy units matching this filter will be attacked, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side. It does not affect the move-to-targets CA.
* '''leader_weight'''=2: (number >= 0) {{DevFeature1.13|2}} A factor specifying how much more valuable the AI considers side leaders than non-leader units in the attack evaluation. This is also used to determine whether an attack by the leader is safe (see description of the combat candidate action above).
* '''leader_additional_threat'''=1: (number > 0) {{DevFeature1.13|2}} If threatened_leader_fights=yes, the threat at the attack position may be larger by this factor for the leader to leave the keep for an attack.
* '''leader_attack_max_units'''=3: (number >= 0) {{DevFeature1.13|2}} A number specifying how many enemy units within reach are acceptable when determining whether an attack by the leader is safe (see description of the combat candidate action above).
* '''move_cost_factor'''=2: (number >= 1.1) The factor by which the move cost to a goal hex may be larger than the distance to the goal hex for a move to be considered "efficient". See description above. 1.1 is used if this is set to values smaller than 1.1. Smaller values might lead to better behavior, while larger values might speed up the AI.
* '''weak_units_first'''=no: (boolean) If set to 'yes', inverts the order in which units are considered by the combat CA. Attacks are then done in order of increasing hitpoints of the attackers.
* '''skip_combat_ca'''=no: (boolean) If set to 'yes', the fast combat CA is not used. The default AI's high_xp_attack and combat CAs remains in place in this case.
* '''skip_move_ca'''=no: (boolean) If set to 'yes', the fast move-to-targets CA is not used. The default AI's retreat, villages and move-to-targets CAs remains in place in this case.
* '''threatened_leader_fights'''=no: (boolean) {{DevFeature1.13|2}} By default, the AI leader will not attack if the threat at the attack position is too high. If this key is set to 'yes', the leader will attack if the threat there is not larger than the threat at his current position multiplied by the value of 'leader_additional_threat'. This is meant as an option for the endgame: when the AI leader is under attack, he might as well go down fighting.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''aggression''': The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to set how aggressive the AI should attack. It works in roughly the same way as the default AI aspect:
** The value of (1 - aggression) determines how much the AI values its own units compared to the enemy's units. Thus, aggression=0 means that attacks are only done if the AI expects to deal (roughly) the same amount of damage as it will receive. aggression=1 means that expected damage to the AI's units is not considered, only the expected damage to enemy units matters.
** Damage is calculated as a combination of hitpoints and chance to die, in "gold equivalent units".
** Unlike the default AI, aggression is set to 1 for values larger than 1. Allowed values are thus anything from -infinity to +infinity, although only -infinity to +1.0 make sense.
*'''[avoid]''': {{DevFeature1.13|2}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.
*'''attacks aspect''': {{DevFeature1.13|2}} The standard RCA AI [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] used to filter own and enemy units for attacks is now also taken into account as long as neither [filter] nor [filter_second] (see above under 'optional keys') are defined in the [micro_ai] tag.
*'''village_value=1''': (number ranging from 0 to 4) The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to define how much villages should be targeted by the move-to-targets CA. In the Fast MAI, this defines which fraction of the AI units are moved toward village goals (see above for details). If set to 0, villages are ignored as goals.

'''Notes:'''
* The CA evaluation scores of this AI are hard-coded to the same values as those of the respective [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|default candidate actions]]. ca_score is therefore not a valid optional key.
* The fast Micro AI modifies (removes) the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions.

Enabling the Fast Micro AI in its default configuration is as simple as this usage example from the "Fast AI" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=fast_ai
action=add
[/micro_ai]

== Generalized Goto Micro AI (ai_type=goto) ==

The Goto Micro AI provides a highly configurable method of sending a unit (or units) to a location or set of locations. The units to be moved are defined using a [[StandardUnitFilter|Standard Unit Filter]] (SUF) [alternatively, all side units are used if the SUF is not provided), while the goto locations are given in a [[StandardLocationFilter|Standard Location Filter]] (SLF).

By default, each unit matching the SUF will move toward the closest goal (in terms of turns needed to get there) matching the SLF via the fastest route given the current situation on the map (locations of enemy units etc.), but this behavior can be influenced by the optional keys listed below. Note that this means that a unit's goal might change from one turn to the next depending on the situation on the map.

The behavior of the unit(s) once they reach their goal location(s) is configurable as well. By default, they will stay there until the Goto Micro AI is deleted or changed.

For demonstrations of several Goto Micro AI usages, check out the "Goto" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Goto Micro AI by using
ai_type=goto
in the [micro_ai] tag.

===Goto specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the possible goal locations for the move.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). Note that the area defined by [avoid] is not entered at all, even if the end point of the move would lie outside the area again.
* '''avoid_enemies''': (number>0) By default, units controlled by the Goto Micro AI will not take enemy units into account for route finding, other than the enemies' ZoCs. By contrast, if this key is set, they will try to avoid traversing hexes on which they can be attacked by enemies. The larger the value of ''avoid_enemies'', the more the units will try to stay out of the enemies' way. Notes:
** Units are willing to take a path that is 'avoid_enemies' movement points longer for each enemy unit that can be avoided by doing so for each hex along the path. As an example, if avoid_enemies=1 and the shortest path crosses 2 hexes that can be reached by 3 enemies each, the unit is willing to take a path that is up to 6 hexes longer instead. If avoid_enemies=10 in the same situation, the unit will take a path up to 60 hexes longer.
** Hexes adjacent to enemy units are always strongly avoided, independent of the value of avoid_enemies.
** avoid_enemies is ignored if 'use_straight_line=true' is set.
** Due to an issue with the path finding code, '''tunnels and teleports are ignored in Wesnoth 1.14 and before''' if 'avoid_enemies' is used. This has been fixed in Wesnoth 1.15.
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs.
* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units to be moved. Defaults to all units of the side if not defined. The filter automatically includes the side= key set to the AI side.
* '''ignore_enemy_at_goal'''=no and '''ignore_units'''=no: (boolean) In the default configuration, the Goto MAI does not move units if the path to all goal hexes is blocked by enemies. It is therefore possible to disable the Goto MAI by putting enemy units on all the goal hexes. That can be changed if either of these two keys is set to 'yes'.
** 'ignore_enemy_at_goal=yes' makes the AI choose its goals while disregarding any enemy units at the goal hexes. Even so, a stiff rating penalty is applied to goal hexes occupied by enemies, thus that unoccupied goal hexes are chosen unless all possible goals are occupied by enemies. Note that this setting ''only'' ignores enemy units at the goal hexes themselves. It is still possible to disable the AI by putting enemies all around the goals.
** 'ignore_units=yes' let's the AI ignore ''all'' enemy units when deciding which goal hex(es) to move toward.
** In both cases, enemies are only ignored for deciding which unit to move toward which goal hex. For the actual move itself, all enemies and their ZoCs are considered as usual.
** Both options only take effect if neither avoid_enemies is used, nor use_straight_line is set to 'yes', as neither of these consider enemies as blockers. Or in other words, if avoid_enemies is used, or use_straight_line=yes, it is unnecessary to set ignore_enemy_at_goal or ignore_units to yes.
* '''release_unit_at_goal'''=no: (boolean) By default, a unit that reaches a goal location will stay there until the Goto Micro AI is deleted or changed (or until the conditions specified in the [goto_goals] SLF change). If this parameter is set, a unit that has reached its goal will not be controlled by this Micro AI any more starting from the next turn.
* '''release_all_units_at_goal'''=no: (boolean) Same as ''release_unit_at_goal'', but this will deactivate the Goto Micro AI for all units once the first unit reaches a goal.
* '''remove_movement'''=yes: (boolean): {{DevFeature1.15|11}} By default, when the Goto MAI cannot move a unit (for example, because the path is blocked by enemies), its movement points are still removed. If this option is set to 'no', this step does not happen, so that other AI candidate actions (or even another Goto MAI with different parameters) can take over instead.
* '''unique_goals'''=no: (boolean) If set to 'yes', each unit will be sent to a different goal location. Note that the best goals are recalculated each turn, so a unit might choose a different goal this turn from what it was heading for during the previous turn if the situation on the map has changed. Also note that if there are more units than goal locations, the left over units will not be handled by the Goto MAI but follow default behavior instead.
* '''use_straight_line'''=no: (boolean) By default, units choose the route by which they will get to their goal locations in the smallest number of turns. If this parameter is set to 'yes', a straight line route (or something pretty close to it at least) will be chosen instead, irrespective of whether this leads into a dead end, whether it is blocked by enemies, etc.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

'''Notes:'''
* Depending on the parameters used, the Goto Micro AI might require a lot of path finding to be done. Thus, while it is possible to set up this AI to move many units to many different locations, a usage like that might require quite a long calculation time.

===Goto Micro AI example usages:===

Here are several examples of goto [micro_ai] tag usages from the "Goto" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
* Send a unit toward a castle (similar to the RCA AI's Goto Candidate Action, but avoiding dead ends and areas ZoCed by enemies)
[micro_ai]
side=2
ai_type=goto
action=add
ca_id=messenger1

[filter]
id=messenger1
[/filter]
[filter_location]
x,y=6-7,2-4
terrain=C*
[/filter_location]
ca_score=210001
[/micro_ai]
* Send all units of the side toward the southern border of the map
[micro_ai]
side=8
ai_type=goto
action=add

[filter_location]
y=33
[/filter_location]
avoid_enemies=1
[/micro_ai]
* Send units to the four corners of the map (with each unit going to a different corner).
[micro_ai]
side=7
ai_type=goto
action=add

[filter_location]
x=1,1,44,44
y=1,33,1,33
[/filter_location]
unique_goals=yes
[/micro_ai]
* Set up a guardian unit that doesn't move while no enemy unit is within 8 hexes (ironically, the Goto Micro AI can be used to keep units in place, although using one of the Guardian Micro AIs might often be a better idea)
[micro_ai]
side=3
ai_type=goto
action=add

[filter]
id=guard1
[/filter]
[filter_location]
[filter]
id=guard1
[/filter]
[not]
[filter]
side=1
[/filter]
radius=8
[/not]
[/filter_location]
[/micro_ai]

== Guardian Micro AIs ==
=== General Comments on the Guardian Micro AIs ===

The Guardian Micro AIs can be used to set up different kind of guardian behaviors for a unit or a set of units. Four different types of guardians are available and are described below.

For a demonstration of several different guardian behaviors, check out the "Guardians" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

=== Return Guardian (ai_type=return_guardian)===

A 'return guardian' is a variation of the standard Wesnoth guardian. It has an assigned guard position (GP) to which it returns after attacks on approaching enemies:
* If at GP with no enemy in reach, do nothing.
* If at GP with an enemy in reach, attack. Note that the attack is done by the default AI, which might result in the guardian not attacking if the enemy is deemed too strong (this can be influenced by setting the default ''aggression'' value to a different value).
* If not at GP, return there, no matter whether an enemy is in reach or not.
* If enemies are blocking the way back to GP, do your best to move around them.
* If the guardian ends up next to an enemy on the way back, attack that enemy after the move.

Enable the Return Guardian Micro AI by using
ai_type=return_guardian
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|Standard Unit Filter]] selecting the units controlled by this Micro AI.
** One or the other is required
** If both are given, [filter] takes priority over id=
** The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
** If several units match the filter, the order in which they are controlled is not guaranteed. If the order matters, set up several MAIs using the id= key and different values for ca_score=.
* '''return_x,return_y''': The coordinate of the hex the unit returns to after each attack. {{DevFeature1.15|0}} '''return_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=100010: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. This AI consist of 2 CAs, one with score <tt>ca_score</tt> the other with <tt>ca_score-20</tt>. The default value is set so that the first CA gets executed right before the default combat CA, and the other right after. It usually will not make sense to change this value, but it is possible to do so for custom applications. {{DevFeature1.13|6}}: This is now changed to 100100 and 99900 in order to avoid conflicts with the new high_XP_attacks candidate action.

Here's an example of a return guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=return_guardian
action=add

[filter]
id=return1
[/filter]
return_x,return_y=20,2
[/micro_ai]

===Stationed Guardian (ai_type=stationed_guardian) ===

A 'stationed guardian' is another variation of the standard Wesnoth guardian with a somewhat more complex behavior than that of the 'return guardian'. Two positions are defined for it, a 'station' and a 'guarded location', as well as a distance. The behavior is as follows:
* If no enemy is within 'distance' of the guard's current position, do nothing. This is independent of the guardian being at its station or not.
* Otherwise: If an enemy is within 'distance' of the guard, but not also within the same distance of the guarded location and the station (all of this simultaneously), move the guard in the direction of the station (or keep the guard in place if the station is unreachable).
* Otherwise:
** Pick the enemy unit that is closest to the guarded location.
** If we can reach it, pick the adjacent hex with the highest defense rating and attack from there.
** If not in reach, move toward this unit.

Enable the Stationed Guardian Micro AI by using
ai_type=stationed_guardian
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|Standard Unit Filter]] selecting the units controlled by this Micro AI.
** One or the other is required
** If both are given, [filter] takes priority over id=
** The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
** If several units match the filter, the order in which they are controlled is not guaranteed. If the order matters, set up several MAIs using the id= key and different values for ca_score=.
* '''distance''': The distance parameter as explained above
* '''station_x,station_y''': The x and y position of the hex that serves as the guardians station. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.
* '''guard_x, guard_y''': The x and y position of the guarded location. {{DevFeature1.13|0}} These are now optional keys, defaulting to station_x,station_y if not provided. {{DevFeature1.15|0}} '''guard_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs.

Here's an example of a stationed guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=stationed_guardian
action=add

[filter]
id=stationed1
[/filter]
distance=4
station_x,station_y=2,14
guard_x,guard_y=3,13
[/micro_ai]

=== Coward (ai_type=coward) ===

Cowards are units that, like guardians, sit around doing nothing until an enemy comes into range. Unlike guardians, however, they run away once enemies approach. Applications might be wild animals, unarmed civilians getting in the way of a battle, etc. The coward macro can be called with two optional locations, 'seek' and 'avoid':
* If neither is given, the coward retreats to the position farthest away from the approaching enemies.
* If 'seek' is given, it preferentially goes toward that location (but getting away from enemies takes priority).
* If 'avoid' is given, it in addition tries to avoid that location (with both maximizing distance from enemies and going toward 'seek' taking priority).
* Both 'seek' and 'avoid' may consist of only one coordinate ('x' or 'y'), in which case not a single hex, but a line of hexes is sought or avoided.

Enable the Coward Micro AI by using
ai_type=coward
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|Standard Unit Filter]] selecting the units controlled by this Micro AI.
** One or the other is required
** If both are given, [filter] takes priority over id=
** The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
** If several units match the filter, the order in which they are controlled is not guaranteed. If the order matters, set up several MAIs using the id= key and different values for ca_score=.
* '''distance''': The distance within which an enemy must be to "scare" the unit

'''Optional keys:'''

* '''attack_if_trapped'''='no': {{DevFeature1.13|0}} With the default settings, a coward never attacks. If this key is set to 'yes', the coward attacks the weakest (lowest hitpoints) enemy next to which it ends up after moving (such as a cornered animal would do, blindly lashing out without regards for its own safety).
* '''avoid_x, avoid_y''': The x and y coordinate of the hex to avoid. {{DevFeature1.15|0}} '''avoid_loc''' can be used instead with a named/special location.
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units from which the cowards flee. If not set, this defaults to all enemy units. Note, however, that no "enemy of AI side" condition is added if [filter_second] is specified, meaning that it can include allied and/or enemy units as desired (and even units on the same side as the coward).
* '''seek_x, seek_y''': The x and y coordinate of the hex to seek. {{DevFeature1.15|0}} '''seek_loc''' can be used instead with a named/special location.

Here's an example of a coward [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=coward
action=add

[filter]
id=coward3
[/filter]
distance=5
seek_x,seek_y=24,5
avoid_x,avoid_y=24,15
[/micro_ai]

=== Zone guardian (ai_type=zone_guardian) ===

A zone guardian is a unit that, as the name says, guards a zone. It moves randomly inside this zone until an enemy enters it (or a separately defined enemy zone, see below). Applications might be the defense of a castle, a nesting area or for protecting an unit. The zone macro can be called with an optional SLF, [filter_location_enemy]:
* If not specified, the zone guard attacks any enemy coming inside its guard zone.
* If [filter_location_enemy] is given, it attacks any enemy entering this zone and once there are no more enemies, it goes back to patrol in its basic zone.

Enable the Zone Guardian Micro AI by using
ai_type=zone_guardian
in the [micro_ai] tag together with the following keys:

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|Standard Unit Filter]] selecting the units controlled by this Micro AI.
** One or the other is required
** If both are given, [filter] takes priority over id=
** The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
** If several units match the filter, the order in which they are controlled is not guaranteed. If the order matters, set up several MAIs using the id= key and different values for ca_score=.
* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] designating the zone to guard.

'''Optional keys:'''
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs.
* '''[filter_location_enemy]''': A [[StandardLocationFilter|Standard Location Filter]] designating the zone where enemies have to be attacked. If not given, it defaults to [filter_location].
* '''station_x,station_y''': By default, the zone guardian moves randomly within the zone if there is no enemy to attack. However, if station_x/y is given, it moves to this position instead during turns when it does not have an enemy to attack. This position does not need to be inside the zone defined above. Note: obviously it does not make sense to define [filter_location], [filter_location_enemy] and station_x/y all at the same time. Only [filter_location] and either one of the latter two (or none of them) should be provided for any zone guardian. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.

Here's an example of a zone guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=zone_guardian
action=add

[filter]
id=zone3
[/filter]
[filter_location]
x,y=22-31,4-11 # This is intentionally chosen to extend past the lake
terrain=W*
[/filter_location]
station_x,station_y=32,8
[/micro_ai]

== Hang Out Micro AI (ai_type=hang_out) ==

The Hang Out Micro AI instructs units of the AI side to "hang out" around a certain location, or locations, until a condition for mobilizing the side is met. If none of the optional keys are given, the AI controls all units of the side to hang around the leader while moving off castle tiles to make room for recruiting.

The AI works by moving each unit to its best hex first using the minimum amount of movement points required for this move. Once all AI units are in position, movement points are set to zero for all of them simultaneously such that they cannot be used by other AI candidate actions. This is done because the mobilizing condition might be met as result of one of the moves of the Hang Out AI, after which we want units to be able to continue with other AI actions.

For a demonstration, check out the "Hang Out and Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Hang Out Micro AI by using
ai_type=hang_out
in the [micro_ai] tag.

===Hang Out specific keys for the [micro_ai] tag:===

'''Required keys:'''

There are no required keys. In its default configuration, the Hang Out MAI controls all units of a side, keeping them as close to the side leader(s) as possible while moving off castle tiles to make room for recruiting. For this purpose, the candidate action score defaults to 170,000, which is just below the score of the default recruiting CA.

'''Optional keys:'''

* '''[avoid]''': A [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). If neither of these two exists, this parameter is set to default to all castle terrain (<tt>terrain=C*,C*^*,*^C*</tt>) so that units move off the castle to make room for recruiting. Note that this does not include keep terrain, otherwise the leader would be moved off the keep as well.
* '''ca_score'''=170000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 170,000, which means that it is executed after the default recruitment CA, but before most of the other default CAs.
* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Hang Out action (<tt>side=</tt> is always set and does not need to be provided). It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the locations ''near'' which the AI units should hang out. This does not mean that the units only move onto terrain specified here, but that they minimize the distance to such terrain. It defaults to the position of the side leader(s).
* '''[mobilize_condition]''': Contains ([[ConditionalActionsWML#Condition_Tags|WML Condition Tags]]) Once the condition set up here has been met, the Hang Out MAI is disabled and the side goes over to other AI activity. The Hang Out MAI remains disabled after this, even if the condition is not met any more later in the scenario.
* '''mobilize_on_gold_less_than''': (integer) Since side gold cannot be checked in a WML condition tag without storing it in a variable first, this key is provided separately. It disables the Hang Out Micro AI once the side gold goes below the value specified here for the first time.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

'''Notes:'''

* The Hang Out AI still takes effect if no locations to hang out at are found or if all map locations are to be avoided. In that case, it simply keeps all units at their current locations.

This is an example of a Hang Out Micro AI configuration from the "Hang Out and Messenger" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=hang_out
action=add

[avoid]
terrain=C*,H*,M*,A*,S*,*^F*
[/avoid]
[mobilize_condition]
[have_unit]
side=1
count=7-99
[/have_unit]
[/mobilize_condition]
[/micro_ai]

== Healer Support Micro AI (ai_type=healer_support) ==

The Healer Support Micro AI configures the healers of a side to stay behind the battle lines and heal injured and/or threatened units rather than participate in combat under all circumstances. You can set different levels of aggressiveness for the healers.

'''Notes'''
* By default, ''all'' healers of the AI side are controlled by this AI. This includes in particular also the side leader, if the leader is a healer. If you do not want the leader to be included (and possibly be moved away from the keep etc.) use the [filter] tag with canrecruit=no (see below).
* It is not always better to use this Micro AI than the default AI, as it takes healers (which can be strong units) away from the pool of units to choose for attacks.
* {{DevFeature1.15|3}} This Micro AI now takes unit guardian status and the passive_leader aspect into account.

For a demonstration, check out the "Healers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Healer Support Micro AI by using
ai_type=healer_support
in the [micro_ai] tag.

===Healer Support specific keys for the [micro_ai] tag:===

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the healer units. If set, only units on the AI side passing this filter ''and'' having the healing ability are considered by this Micro AI.
*'''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting units to receive healing. If set, only units on the AI side passing this filter ''and'' the other healee selection criteria will be selected for healing by this Micro AI.
* '''aggression'''=1.0: (float) Sets the aggressiveness of the AI. This parameter is set up as a float to accommodate future functionality, but it currently acts as a boolean: if set to zero, the AI will never let its healers participate in combat, for all other values it allows them to attack after all other units have attacked and if the healers cannot find any more units to support. The former behavior might be appropriate in scenarios with only one or few valuable healers, while the latter might work better in scenarios with many healers.
* '''injured_units_only'''=no: (boolean) If set to 'yes', the AI will only move healers next to units that are already injured and skip units that currently have full hitpoints, but might get injured during the next enemy turn.
* '''max_threats'''=9999: (integer) The maximum allowable number of enemies that can attack a hex in order for it to be considered for a healer. As an example, setting 'max_threats=0' means that the AI only moves healers to locations that are entirely safe from the enemy (assuming that none of the units currently on the map dies). Note that the value of this key is checked against the number of enemies that can make it to the hex, not the number of adjacent hexes from which the healer could be attacked.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI. Note: as attacks by the healers are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

'''Notes:'''
* The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]].
* The CA evaluation scores of this AI are hard-coded. It does not work otherwise.

This is an example of a Healer Support Micro AI configuration from the "Healers" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=healer_support
action=add

aggression=0
[/micro_ai]

== Lurkers Micro AI (ai_type=lurkers) ==

The Lurker Micro AI controls some or all units of a side in "lurker mode". A lurker is a unit that is capable of moving across most terrains, but that only stops on and attacks from specific terrain. It might also have the ability to hide on this terrain (which is the reason why it is called a lurker).

Lurkers move individually without strategy and always attack the weakest enemy within their reach. If no enemy is in reach, the lurker does a random move instead - or it just sits and waits (lurks).

For a demonstration of different types of lurker behavior, check out the "Lurkers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Lurkers Micro AI by using
ai_type=lurkers
in the [micro_ai] tag

===Lurkers specific keys for the [micro_ai] tag:===

'''Required keys:'''
* '''[filter]''': Specifies which units of the side are controlled by the Lurker Micro AI. This is a [[StandardUnitFilter|Standard Unit Filter]]. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': Specifies the terrain from which the lurkers attack. This is a [[StandardLocationFilter|Standard Location Filter]].

'''Optional keys:'''
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs.
* '''[filter_location_wander]''': Specifies the terrain on which lurkers end their moves if there is no enemy in reach. This is a [[StandardLocationFilter|Standard Location Filter]]. If [filter_location_wander] is not given, it defaults to [filter_location].
* '''stationary'''=no: (boolean) If set to yes, a lurker never moves if there is no enemy within attack range.

Here's an example of [micro_ai] tag usage from the "Lurkers" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=4
ai_type=lurkers
action=add

[filter]
type=Naga Fighter
[/filter]
[filter_location]
terrain=W*,S*
[/filter_location]
[filter_location_wander]
terrain=W*
[/filter_location_wander]
[/micro_ai]

== Messenger Escort Micro AI (ai_type=messenger_escort) ==

The Messenger Escort Micro AI lets you define a set of waypoints through which it tries to move one or several of its units, the messenger(s). The other units escort the messenger, trying to protect it and attacking enemies that are in its way. Note that a messenger might not strictly hit intermediate waypoints, but that getting close is good enough, especially if a waypoint is occupied by an enemy unit. It does, however, always try to get to the last waypoint.

'''Notes on the use of several messengers:''' {{DevFeature1.13|0}}
* This Micro AI can control several messengers at the same time, which can but do not have to move in a group. They can be put on the map altogether in one location, or be spread out on the map or across different turns.
* The farther a messenger has moved through the chain of waypoints, the higher a priority it is for the AI, meaning that farther advanced (on the map) messengers are moved first, and that the escort units try to clear the way and stay with those messengers more so than with those further back on the map. This order can be inverted using the invert_order= key.
* If several messengers are on the map, escort units might move from one to the other, the AI making a judgement call where they are needed most. Closeness to a messenger is generally the most important criterion, but not the only one.
* If a messenger dies, the escort units previously staying with it now join one of the other messengers if there are any left (otherwise they follow default AI behavior).
* If you want certain escort units to stay always with the same messenger, use several messenger [micro_ai] tags with different [filter]/[filter_second] combinations.

For a demonstration, check out the "Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Messenger Escort Micro AI by using
ai_type=messenger_escort
in the [micro_ai] tag.

===Messenger Escort specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': {{DevFeature1.13|0}} (Previous to 1.13.0, only id= was allowed.) The id of a unit or a [[StandardUnitFilter|Standard Unit Filter]] selecting the units controlled by this Micro AI.
** One or the other is required
** If both are given, [filter] takes priority over id=
** The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
* '''waypoint_x,waypoint_y''': Comma-separated list of waypoint coordinates through which the messenger will go in the given order to reach its goal, given by the last coordinate. If you want the messenger to go directly to the goal, simply enter a single x,y coordinate here. Note that the messenger does not have to hit each waypoint exactly (except for the final one), getting close to them is good enough. {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|11}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Note that the Messenger Escort AI consists of 3 CAs with scores ranging from <tt>ca_score-2</tt> to <tt>ca_score</tt>.
* '''enemy_death_chance'''=0.67 and '''messenger_death_chance'''=0.0: (both floats; ranging from 0 to 1) If the messenger is adjacent to an enemy at the end of the move, it will only attack the enemy if the chance of death of the enemy is >= enemy_death_chance and if the messenger's chance of death is <= messenger_death_chance (or if it is an attack at a range for which the enemy does not have a weapon).
* '''[filter_second]''': {{DevFeature1.13|0}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the escort units. If not set, this defaults to all enemy units. The filter automatically includes the side= key set to the AI side.
* '''invert_order'''=no: {{DevFeature1.13|0}} If set to 'yes', the order of priority with which messenger units are considered is inverted, starting with the messenger unit that is the least advanced on the map (see description above). In most cases, selecting this option results in worse performance of the AI, so use it with caution. (And obviously it has no effect at all if there is only one messenger controlled by the AI.)

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|11}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of [micro_ai] tag usage from the "Messenger Escort" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=messenger_escort
action=add

[filter]
id=messenger
[/filter]
waypoint_x=31,24,27,28
waypoint_y=20,14,7,1
[/micro_ai]

== Patrol Micro AI (ai_type=patrol) ==

The defines a number of waypoints for a unit (or units) to follow. Options can be set whether the route should be followed in a loop, as an out-and back, only once, whether units encountered along the way should be attacked, etc.

With the default settings, getting to the next waypoint takes priority over attacking for a patroller, but this can be overridden (as of '''Wesnoth 1.15.12''', using the '''attack_range''' option). Unless instructed otherwise, the AI thus prefers to move the patrol unit around enemies rather than straight for them. Also, if a waypoint is occupied by a unit the AI is not instructed to attack, it will (eventually) abandon that waypoint once it gets close enough and move on to the next one.

For a demonstration of several different patrol behaviors, check out the "Patrols" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Patrol Micro AI it by using
ai_type=patrol
in the [micro_ai] tag.

===Patrol specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|Standard Unit Filter]] selecting the units controlled by this Micro AI.
** One or the other is required
** If both are given, [filter] takes priority over id=
** The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
** If several units match the filter, the order in which they are controlled is not guaranteed. If the order matters, set up several MAIs using the id= key and different values for ca_score=.
* '''waypoint_x,waypoint_y''': Comma-separated lists of the waypoint coordinates through which the patrol travels (in order). {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''Optional keys:'''

* '''attack''': By default (if this key is not set), the patrol unit attacks any unit it ends up next to after a move, or that is within '''attack_range''' (see below). Alternatively, this parameter can be set to a comma-separated list of unit ids. If that is done, the patrol only attacks these units when it ends up next to them or if it gets within attack_range. It ignores any other unit. This can in turn be used to have the patroller not attack at all, by setting ''attack='' to a non-existing id. The exception to this is an enemy on the last waypoint with ''one_time_only=yes'', which will always be attacked.
* '''attack_range'''=1: {{DevFeature1.15|12}} If the patrol comes within this many hexes of an enemy unit, it interrupts its patrol route and attacks that enemy (assuming it still has enough movement left to get to the enemy). The '''attack=''' instructions are taken into account for this. Note that the patrol generally tries to move around enemies, which means that for the default value of 1, enemies are usually not within attack range, except at the end of the move.
* '''attack_invisible_enemies'''=no: {{DevFeature1.15|12}} If set to 'yes', the unit also attacks invisible enemies (according to the criteria set by '''attack''' and '''attack_range''').
* '''ca_score'''=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|RCA AI candidate actions]]. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs.
* '''one_time_only'''=no: (boolean) If set to 'yes', the unit goes through the patrol route only once and then hangs out at the last waypoint. It also always attacks any enemy unit on the last waypoint, independent of what ''attack='' is set to.
* '''out_and_back'''=no: (boolean) By default, a patrol unit returns to the first waypoint after reaching the last, doing the patrol route as a loop. If this parameter is set to 'yes', the unit instead reverses its course and perpetually does out and backs of the route.

Here's an example of [micro_ai] tag usage from the "Patrols" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=patrol
action=add

[filter]
id=Konrad
[/filter]
waypoint_x=9,24,25
waypoint_y=21,23,15
one_time_only=yes
attack=Gertburt
[/micro_ai]

== Protect Unit Micro AI (ai_type=protect_unit) ==

The Protect Unit Micro AI tries to move one or several units to a given location while keeping them safe from enemy attacks. It does so by keeping the protected units away from enemy units and close to friendly units. Other units on the AI side are controlled by the default Wesnoth AI.

For a demonstration, check out the "Protect Unit" and "The Elves Besieged" scenarios from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Protect Unit Micro AI by using
ai_type=protect_unit
in the [micro_ai] tag.

===Protect Unit specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[unit]''': A separate [unit] tag is required for each protected unit(s). Each tag has required keys '''id''', '''goal_x''', '''goal_y''' for each unit, as shown in the example below. {{DevFeature1.15|0}} '''goal_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''disable_move_leader_to_keep'''=no: (boolean) If set to 'yes', side leaders protected by this AI do not try to return to their keep. This is necessary for this Micro AI to work with units that are side leaders and that are supposed to move to an off-keep location.

'''Notes:'''
*The Protect Unit Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|move leader to keep candidate action]].
* The CA evaluation scores of this AI are hard-coded. It does not work otherwise.

Here's an example of [micro_ai] tag usage from the "HttT: The Elves Besieged" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=protect_unit
action=add

[unit]
id=Delfador
goal_x,goal_y=1,2
[/unit]
[unit]
id=Konrad
goal_x,goal_y=1,1
[/unit]

disable_move_leader_to_keep=true
[/micro_ai]

== Recruiting Micro AI==
=== General Comments on the Recruiting Micro AIs ===

The Recruiting Micro AI replaces the default recruitment AI by alternative recruiting patterns. Currently there are two recruiting algorithms you can choose from, random recruiting and the rush recruiting used in the new (as of Version 1.11.1) Experimental AI (see below).

For a demonstration of a different recruiting pattern, check out the "Recruiting" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. You can also explore the unit choices by watching the Experimental AI in a multiplayer game.

'''Note:''' Obviously, the Recruitment Micro AI modifies the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|recruitment candidate action]].

=== Random Recruitment AI (ai_type=recruit_random) ===

This AI randomly selects a unit type from the recruitment list of the side. The probability of choosing each type and the behavior in low-gold situations can be influenced with optional parameters.

Enable the Random Recruiting Micro AI by using
ai_type=recruit_random
in the [micro_ai] tag.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''ca_score'''=180000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 180,000. This is identical to the default Recruiting CA which it replaces.
* '''[probability]''': This tag sets the probability of selecting the given unit type. It has two required sub-keys:
** '''type''': comma-separated list of unit types to which this probability is to be applied
** '''probability''': (non-negative float) The probability with which these unit types is to be selected. All unit types for which no [probability] tag is defined receive a default probability of 1.0, thus values should be chosen relative to that. As an example, in the code below swordsmen and peasants are given a probability of 8, while no other units have assigned probabilities. Thus, each of these two unit types is 8 times more likely to be selected than any other individual unit type.
* '''skip_low_gold_recruiting'''=no: (boolean) By default, the random recruitment AI chooses a unit to recruit only from those types for which it has sufficient gold. If this parameter is set to 'yes', it will instead choose from all available unit types and end recruiting for the turn if there is not enough gold to recruit it this turn (even if other, affordable unit types exist).

Here's an example of a random recruiting [micro_ai] tag usage from the "Recruiting" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=recruit_random
action=add

[probability]
type=Swordsman,Peasant
probability=8
[/probability]

skip_low_gold_recruiting=yes
[/micro_ai]

=== Rush Recruitment AI (ai_type=recruit_rushers) ===

This AI replaces the default recruiting with the recruiting used in the Experimental AI [[Experimental_AI#Recruitment|as described here]].

Enable the Rush Recruiting Micro AI by using
ai_type=recruit_rushers
in the [micro_ai] tag.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''ca_score'''=180000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 180,000. This is identical to the default Recruiting CA which it replaces.
* {{DevFeature1.15|2}} '''high_level_fraction'''=0: (non-negative number) The approximate fraction of units of level 2 or higher to be recruited. This is defined as fraction of units on the map, not of new units being recruited during a turn or over several turns (which makes a difference if there are already units on the map). The effect is also cumulative per level (starting from level 2), meaning that 1/3 of L2 units will be recruited in the example above, 1/3*1/3=1/9 L3s etc. The default value is zero, which leaves the high-level unit recruiting to the default Experimental AI algorithm resulting usually in very few such units being recruited.
* '''randomness'''=0.1: (number) A random number is applied to the rusher recruit engine's score to prevent the recruitment pattern from being too predictable. 0 causes no randomness to be applied, while larger numbers increase the random effect. A value of 1-2 generates results in which the random effect is approximately equal to the scored effect. Extremely high values are essentially entirely random.
* {{DevFeature1.17|6}} '''reset_cache_each_turn'''=no: (bool) Many of the operations of the rush recruitment evaluation are expensive and are therefore cached. For the most part, this cache can be kept from turn to turn, but in case there are events that change, for example, the map or the recruit list, this parameter can be set to 'yes' to force a reset of the cache each turn.

Here's an example of a rush recruiting [micro_ai] tag usage from the "Recruiting" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=recruit_rushers
action=add
[/micro_ai]

== Simple Attack Micro AI (ai_type=simple_attack) ==

The Simple Attack Micro AI is meant as an addition to the default combat candidate action for when one wants to force the AI to do attacks that it would otherwise not do (for example on units that are 1 XP from leveling) or to execute certain attacks before all others (for example, attack with all "expendable" units first). It is not set up to be a replacement for the default attacks. Some notes:

* The algorithm is different from and simpler than that of the default combat CA. For example, no attack combinations are considered, only individual attacks. As a result, the [[AiWML#List_of_AI_Aspects|default aspects]] (aggression, caution, [avoid], ...) are not taken into account. Also, if lots of units are involved, evaluation of this Micro AI is potentially quite a bit slower than of the default attacks.

* If an attack matching the Standard Unit Filters described below is found, this attack will always be executed, no matter how bad the odds are. Thus, this Micro AI can be used to force the AI to do attacks it would otherwise avoid.

* Other than selecting the attacker/defender units, this AI is currently not configurable. Let us know if you would like to see certain options to be added. (No guarantees that we will add them, but we will definitely consider them.)

For a demonstration, check out the "Simple Attack" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Simple Attack Micro AI by using
ai_type=simple_attack
in the [micro_ai] tag.

===Simple Attack specific keys for the [micro_ai] tag===

'''Required keys:'''

There are no required keys. It is, however, in general not desirable to use this AI without at least one of the optional Standard Unit Filters below, as this AI is not meant as a replacement of the default combat candidate action.

'''Optional keys:'''

* '''ca_score'''=110000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 110,000, which means that it is executed right before the default combat candidate action.
* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Simple Attack action. It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units the AI should attack. It defaults to all enemy units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.
* '''weapon'''=-1: (integer) The number of the weapon that should be used for this attack. Weapon numbers start at 1 (not 0). -1 stands for "best weapon" (by whatever criterion the AI chooses to use). '''Available from Wesnoth 1.11.8'''

Below are 2 examples of Simple Attack Micro AI configurations from the "Simple Attack" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. The first one shows how to force the AI to attack with all Soulless and Walking Corpse units first:
[micro_ai]
side=2
ai_type=simple_attack
action=add

ca_score=110000
[filter]
type=Soulless,Walking Corpse
[/filter]
[/micro_ai]

The second example executes attacks by Soulless on all enemy units that are 1 XP from leveling. Note that the Lua code in the preload event is there simply in order to code the "1 XP from advancing" condition. It is not needed for most other SUFs, as can be seen in the previous example.
[event]
name=preload
first_time_only=no
[lua]
code=<<
function close_to_advancing(unit)
if (unit.experience >= unit.max_experience-1) then
return true
else
return false
end
end
>>
[/lua]
[/event]

[event]
name=prestart
[micro_ai]
side=2
ai_type=simple_attack
action=add

ca_score=110001
[filter]
type=Soulless # No Walking Corpses; L0 units don't advance enemy
[/filter]
[filter_second]
lua_function = "close_to_advancing"
[/filter_second]
[/micro_ai]
[/event]
Several Simple Attack Micro AIs can be combined for the same AI side. The two examples above are both used (note the different values for ca_score) in the "Simple Attack" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

== Custom Micro AIs ==

{{DevFeature1.13|5}}

From 1.13.5 onwards, adding a new Micro AI can be easily done without altering any core files or overriding the micro_ai tag. The [micro_ai] tag now looks up its ''ai_type'' parameter in the <code>wesnoth.micro_ais</code> table and uses the micro AI setup function found there to determine which keys are required and allowed and what candidate actions to add.

A micro AI setup function takes as its single parameter the contents of the [micro_ai] tag and returns three separate values:
*'''required''': A list of required keys and tags, as strings. Tags are indicated by enclosing them within square brackets in the string. If a key or tag in this list is missing from the [micro_ai] tag, an error will be printed. {{DevFeature1.17|6}} In order to enable better error handling, the syntax of this table has been changed. It is now of format <syntaxhighlight lang='lua' inline>{ param1 = 'param1_type', ... }</syntaxhighlight>. The supported parameter types can be found at the link to examples below.
*'''optional''': Similar to above, a list of optional keys and tags, as strings. No error will be printed if a key or tag in this list is missing, nor will an error be printed if it is present (as would be the case for unrecognized keys or tags). {{DevFeature1.17|6}} The format of this table has been changed in the same way as for 'required'. Also, a warning message is now issued if the '[micro_ai]' tag contains a key or tag that is not listed in either 'required' or 'optional'.
*'''ca_params''': A table specifying the candidate actions that constitute the micro AI. It should contain an ''ai_id'' key (which specifies a base ID to be used for candidate actions of this micro AI) and a series of candidate action definitions. Each candidate action definition is a table containing the following keys:
**'''ca_id''': The ID used for the candidate action. This will be combined with the ''ai_id'' to produce the final ID.
**'''location''': Path to the Lua file that defines the candidate action.
**'''score''': The maximum score for the candidate action. If the [micro_ai] tag specified a ''ca_score'' parameter, the score here should normally be based on that.

(The return statement would thus look like <syntaxhighlight lang='lua' inline>return required, optional, ca_params</syntaxhighlight>.)

'''Examples''' of micro AI setup functions can be found in the [https://github.com/wesnoth/wesnoth/tree/1.14/data/ai/micro_ais/mai-defs default MAI definitions directory]. See the [https://github.com/wesnoth/wesnoth/blob/1.14/data/ai/micro_ais/mai-defs/animals.lua#L4-L12 Big Animals MAI definition] for a simple example. For custom micro AIs, the setup code should be put into a ''[lua]'' tag inside a preload event.

Since the function has full access to the contents of the [micro_ai] tag, it can conditionally add candidate actions to '''ca_params''' depending on the values of other keys within the [micro_ai] tag. It can also perform other actions such as adding facets to an aspect; if it does such things, it should pay attention to the ''action'' key to determine whether it's being added or removed.

There are two useful helper functions that can be used by Micro AI setup functions requiring aspect changes. They can be brought into scope by a line similar to the following:
<syntaxhighlight lang='lua>local MAIH = wesnoth.require("ai/micro_ais/micro_ai_helper.lua")</syntaxhighlight>
* MAIH.add_aspects(side, aspect_params)
* MAIH.delete_aspects(side, aspect_params)

The ''aspect_params'' parameter is an array of tables, each of which contains the following keys:
*'''aspect''': The aspect to change.
*'''facet''': The WML defining the facet. This must include an ''id'' key in order for the aspect to be correctly deleted. For maximum compatibility, incorporate the ''ca_id'' key from the [micro_ai] tag.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

Elensefar

2022-09-22T02:16:44Z

Name: Delete empty line

Elensefar is a coastal city-state among the realm of Wesnoth, situated along the Great River Delta. It is believed to have been founded soon after humans came to the Great Continent. Its name, Elensefar, also shows some connections to the elves, as the elvish capital of Lintanir forest is named Elensia. In addition, Delfador even once referred to it as the "Elense city-state", further showing connections to the elves.

The main city-state is a part of the broader province of Elensefar, including the surrounding lands. Its Eastern border is the city Carcyn, a point sometimes disputed by Wesnoth. Along the north lies the Great River, while the south stretches to the Bay of Pearls. The Western end of the province is the shore of the Great Ocean. Though it often allies with Wesnoth (and is considered by many to be entirely subject to Weldyn), it is not always under complete control of the Wesnothian Crown. Indeed, on more than one occasion the diverse rulers of the city have taken pains to distance themselves from Weldyn, such as in 501 YW (under Lord Maddock), when Elenesfar directly announced itself an independent power from Wesnoth, being somewhat at odds with that great country.

[[Category:World_of_Wesnoth]]

Elensefar

2022-09-22T02:13:34Z

Name: Remove UMC "Saving Elensefar" references

Timeline of Wesnoth

2022-09-22T01:42:08Z

Name: Remove UMC "Saving Elensefar" references

{{Translations}}
This is a chronological history of the country of Wesnoth and surrounding regions, gleaned from written accounts and verbal histories passed down through the generations. Portions of entries surrounded by parentheses and containing a question mark are assumed or unconfirmed information. The history is sorted by era, and within the era by date, using the Foundation of Wesnoth as a base. BW=Before Wesnoth, YW=Years Wesnoth. They function the same way as BC and AD do in our timekeeping system. Each of the eras is summarized before the timeline for that era begins. This history of the Great Continent is a subject of active scholarship.

The world that Wesnoth resides in is called Irdya. Before the Great Fall and the (unchronicled) technological age, this name is only rarely used.

'''Spoiler warning!'''
This page contains plot spoilers to several campaigns.

__NOTOC__
[[#Prehistory - 20 YW: The Founding of Wesnoth|The Founding of Wesnoth]]

[[#20-130 YW: The Taming of the Wild|The Taming of the Wild]]

[[#200-350 YW: The Golden Age of Wesnoth|The Golden Age of Wesnoth]]

[[#350-417 YW: The First Dark Age of Wesnoth|The First Dark Age of Wesnoth]]

[[#417-530 YW: The Turmoil of Asheviere|The Turmoil of Asheviere]]

[[#530-630 YW: The Age of Fear|The Age of Fear]]

[[#628-673 YW: The Silver Age of Wesnoth|The Silver Age of Wesnoth]]

[[#761-816 YW: The Legacy of Black-Eye Karun|The Legacy of Black-Eye Karun]]

[[#After the Great Fall|After the Great Fall]]

== Prehistory - 20 YW: The Founding of Wesnoth ==
During the age of the Founding of Wesnoth, there were two important geographic locations, these being the Green Isle and the Great Continent. Haldric is the main historical figure at this time. This age ends with the founding of Wesnoth as a country in the Great Continent, and with Orcs attacking both elves and men from the sea.

=== Prehistory ===
* Elves and Dwarves inhabit the Great Continent.
* Humans inhabit the distant West.
* Haldric's people colonise the [http://wiki.wesnoth.org/Geography_of_Wesnoth#The_Green_Isle Green Isle] from a continent further to the west.

=== 200 BW ===
* The Lich-Lords arrive on the Green Isle after losing a war in the distant West.
* After a long war Haldric's people come to dominate the Green Isle.
* The 'Wesfolk' and their Lich-Lords are pushed onto marginal lands.

=== 12 BW ===
* The Crown Prince of Southbay discovers the Great Continent.

=== 11-7 BW ===
* The Crown Prince makes several voyages between the Green Isle and the Great Continent.

=== 6 BW ===
* Following these voyages to the Great Continent, the elder Crown Prince falls ill and dies.
* His younger brother is implicated in a plot to kill him.
* As a distraction the younger Prince starts a war with the Wesfolk and their Lich-Lords.
* The Lich-Lords sense they will be destroyed and open gates to the homeland of the Orcs in the West.

=== 5-2 BW ===
* The Green Isle is overrun with Orcs.
* The Wesfolk desert their Lich-Lords as they fear becoming prey for the Orcs.
* [http://wiki.wesnoth.org/CharactersStorys#Prince_HaldricPrince Haldric] leads the evacuation of the survivors to the Great Continent. [http://wiki.wesnoth.org/Mainline_Campaigns#The_Rise_of_Wesnoth '''The Rise of Wesnoth'''] begins.

=== 1 BW ===
* Human settlers, led by Prince Haldric, arrive at the western coast of the Great Continent (the landfall occurs in the future Bay of Pearls) in large numbers.
* Humans arrive in the middle of a simmering dispute between the Elves and Dwarves.
* The Elves and Dwarves are distrustful of humans, and there is a small skirmish.
* Messengers from Wesmere Forest come and ask Haldric to come before the Ka'lian.
* Prince Haldric asks the Four Elvish Lords ([http://wiki.wesnoth.org/CharactersStorys#Lady_Dionli Dionli], [http://wiki.wesnoth.org/CharactersStorys#Lord_Logalmier Logalmier], Aryad, and El'Isomithir) for help and land.
* They set before him four quests to prove his worth, which he completes.

=== 1 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Prince_Haldric Haldric] is granted the plains north and south of the Great River.
* Haldric agrees to a Pact of Mutual Defence with the Elves, but the Ka'lian decides it will betray him and allow humans and orcs to exhaust each other in war if the opportunity presents. Haldric, learning of this, considers the Pact a dead letter.
* The Ruby of Fire is temporarily hidden, and the [http://wiki.wesnoth.org/CharactersStorys#Lich-Lord_Jevyan lich-lord Jevyan] is deceived into believing it is held by the Elves.
* Haldric founds the country of [http://wiki.wesnoth.org/Geography_of_Wesnoth#Wesnoth Wesnoth] in the central plain south of the great River.
* Reign of Haldric I (formerly prince Haldric) begins. [http://wiki.wesnoth.org/Geography_of_Wesnoth#Wesnoth '''The Rise of Wesnoth'''] ends.

=== 2 YW ===
* Orcs, following the ships fleeing from the Green Isle, begin to arrive on the Great Continent.
* These Orcs are defeated by Haldric's forces.
* Some of the Orcish survivors flee back to the Green Isle, others move to attack the Elves.
* King Haldric helps the Elves fight the surviving Orcs.

=== 8 YW ===
* A second wave of Orcs arrive from the Green Isle; these Orcs begin claiming large portions of the northern Great Continent for themselves.
* [http://wiki.wesnoth.org/CharactersStorys#Erlornas Erlornas] of Wesmere is involved in the first direct elvish clash with orcs ([http://wiki.wesnoth.org/Mainline_Campaigns#An_Orcish_Incursion '''An Orcish Incursion'''] takes place in 8-9YW).
* Haldric I publicly repudiates the Pact he spoke with the Elves, refusing to give aid.

=== 9-11 YW ===
* Many Elves are killed in battle by the Orcs.
* Elvish emissaries are turned away from Wesnoth.

=== 12 YW ===
* Orcs fail to take the Wesmere Forest and instead march down the coast, devastating human settlements there.
* Elves refuse to aid the Humans in confronting the Orcs.
* Human refugees from the coastal settlements relocate in what will become known as the Great Central Plain. Dan'Tonk, which will become Wesnoth's largest city, is founded.

=== 20 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Prince_Haldric Haldric I] dies.
* [http://wiki.wesnoth.org/CharactersStorys#Haldric_II Haldric II] ascends to the throne.
* [http://wiki.wesnoth.org/CharactersStorys#Kalenz_2 Kalenz] and [http://wiki.wesnoth.org/CharactersStorys#Landar Landar] escape an orcish invasion of their home in Lintanir Forest. [http://wiki.wesnoth.org/Mainline_Campaigns#Legend_of_Wesmere '''The Legend of Wesmere'''] begins.
* Humans and elves decisively defeat the orcs at Tath, thus halting the orcish advance.
* A new treaty between humans and elves is signed and King Haldric II allows emissaries of the Elves to return to Wesnoth.
* Elves inform [http://wiki.wesnoth.org/CharactersStorys#Haldric_II Haldric II] of the danger posed by the unshielded Ruby of Fire.
* [http://wiki.wesnoth.org/CharactersStorys#Kalenz_2 Kalenz] and [http://wiki.wesnoth.org/CharactersStorys#Landar Landar], later to become successive High Lords of the Elves, are able to sneak into an orcish camp by stealth and assassinate the Great Chief Brurbar. A long orcish civil war for succession follows. The orcs are unable to undertake action against any other race during this period and Wesnoth enjoys a long period during which it can expand with little opposition.

== 20-130 YW: The Taming of the Wild ==
This era is that in which the kingdom of [http://wiki.wesnoth.org/Geography_of_Wesnoth#Wesnoth Wesnoth] expanded and defined its borders, and settled the area which it had claimed for its own. The Taming of the Wild refers to the settling of the unsettled lands, as well as to the colonization of the Northlands. The end of this era is marked by friction between the city-state of [http://wiki.wesnoth.org/Geography_of_Wesnoth#Elensefar Elensefar] and the country of Wesnoth, which will continue for the next several hundred years.

=== 21 YW ===
* Founding of the Great Academy on Alduin.

* [http://wiki.wesnoth.org/CharactersStorys#Kalenz Kalenz] is relieved of command by the Ka'lian. He retires to Lintanir Forest with [http://wiki.wesnoth.org/CharactersStorys#Cleodil Cleodil]. A faction of xenophobic elves begins to gather around [http://wiki.wesnoth.org/CharactersStorys#Landar Landar].

=== 22 YW ===
* While studying at the Academy, [[CharactersStorys#Ardonna_.2F_Ardryn-Na|Ardonna]] resolves to spend the winter researching the Lich Lords' longevity.

=== 23 YW ===
* Action of '''Secrets of the Ancients''' takes place.

=== 25-40 YW ===
* In 25 YW [http://wiki.wesnoth.org/CharactersStorys#Haldric_II Haldric II] sends an expedition to retrieve the Ruby of Fire from its place of concealment.
* Haldric II commissions a Dwarven tribe to build the Sceptre of Fire with the Ruby of Fire as its centerpiece; Elves associated with [http://wiki.wesnoth.org/CharactersStorys#Landar Landar's] faction attack during the transfer. [http://wiki.wesnoth.org/Mainline_Campaigns#Sceptre_of_Fire '''Sceptre of Fire'''] begins.
* Action of '''The Sceptre of Fire''' takes place. Haldric II is informed that the Sceptre was both completed and lost in the year 40. It will not be recovered for nearly 500 years.
* With the death of [http://wiki.wesnoth.org/CharactersStorys#Thursagan Thursagan], the Runemaster, all runemasters are killed and runesmithing is lost for several centuries.

=== 26-50 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Landar Landar] declares himself High Lord of the Elves, leading to civil war.

=== 51 YW ===
* Wesnothian New Writing (the script later called "steel-hand", to distinguish it from the more complex "brush-hand" cursive brought from the [http://wiki.wesnoth.org/Geography_of_Wesnoth#The_Green_Isle Green Isle]) is promulgated by royal decree. From this date all royal documents and public inscriptions are in New Writing. It spreads rapidly via the mercantile class. The older brush-hand writing continues to be used for magical purposes, scholarship, and in certain elevated literary forms.

=== 50-93 YW ===
* Elvish civil war (and [http://wiki.wesnoth.org/Mainline_Campaigns#Legend_of_Wesmere '''The Legend of Wesmere''']) ends. [http://wiki.wesnoth.org/CharactersStorys#Kalenz_2 Kalenz] declared High Lord, begins reorganizing and militarizing Elvish society to fight the orcs. In late 93 YW he cedes control to a reconstituted Ka'lian and retires again to the Forest of Lintanir.

=== 161-164 YW ===
* The newly crowned king sought to make safe once and for all the wildlands that separated the human cities surrounding Weldyn and the coastal regions of Elensefar.
* The grand army of Wesnoth, personally led by the High Council of Archmagi, destroyed all enemies residing within Wesnoth.
* The city-state of Elensefar is formally united to the kingdom. Settlements from it spread north of the river into the new frontier province of Annuvin, carefully avoiding the margins of Wesmere Forest.

=== 164-176 YW ===
* During this twelve year span, the western fortress of Halstead was erected in the very heart of the western wilderlands.

=== 199 YW ===
* Emboldened by the far-reaching arm of Halstead's protection, settlement in the west explodes
* The settlements of Aldril and Carcyn grow to become major cities, the first as an important port due to its position on the Bay of Pearls, and the second as a stop on the road to Elensefar and military outpost along the Great River
* Settlers from Carcyn cross the Great River to establish the first settlements north of it and east of Wesmere.

== 200-350 YW: The Golden Age of Wesnoth ==
The Golden Age of Wesnoth was the time of the great kings, and of peace and prosperity within the kingdom. The Orcs had suffered a grave defeat at the hands of Wesnoth and Elensefar seventy-five years earlier, so they did not pose much of a threat, and whenever they did attack they were quickly defeated. This allowed the army to lessen in size, and the kings of this age to undertake the great public works they are renowned for. The era ends when the king of Wesnoth dies without an heir, and a new dynasty begins.

=== 251 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Cleodil Cleodil], wife of [http://wiki.wesnoth.org/CharactersStorys#Kalenz_2 Kalenz], dies.

=== 350 YW ===
* Disintegration of the Kingdom follows the death of Haldric IV.
* [http://wiki.wesnoth.org/Geography_of_Wesnoth#Elensefar Elensefar] remains a province of Wesnoth but exerts increasing independence due to isolation.
* Treaty between lord of Elensefar and king of Wesnoth signed.

== 350-417 YW: The First Dark Age of Wesnoth ==
The first Dark Age was a time of strife and invasion. When Haldric IV died, he left Wesnoth without a king, and the next 70 years were marked by short-lived dynasties, attacks by ever more aggressive orcs, and the further separation of Wesnoth and Elensefar. The Dark Age ended when Garard I took the throne, and began a new dynasty that would last for several hundred years.

=== 360 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Malin_Keshar Malin Keshar] born in Parthyn.

=== 363 YW ===
* Last of [http://wiki.wesnoth.org/CharactersStorys#Kalenz Kalenz's] children dies. Kalenz, condemned to outlive his offspring by the potion of Crelanu, leaves the Forest of Lintanir and begins wandering the Great Continent.

* Village of Maghre terrorized by a minor necromancer. Action of [http://wiki.wesnoth.org/Mainline_Campaigns#A_Tale_Of_Two_Brothers '''A Tale of Two Brothers'''] takes place.

=== 389 YW ===
* Garard, a future king of Wesnoth, is born.
* [http://wiki.wesnoth.org/CharactersStorys#Malin_Keshar Malin Keshar] returns to Parthyn from the Academy at Alduin. [http://wiki.wesnoth.org/Mainline_Campaigns#Descent_into_Darkness '''Descent Into Darkness'''] begins.

== 417-530 YW: The Turmoil of Asheviere ==
King Garard's dynasty was long-lived and productive, but it was also punctuated by significant turmoil: the end of the first king's reign was marred by orcish and undead raids, and the second was murdered by his own wife and son. It was not until 517 YW that the usurpation of the throne by Queen Mother Asheviere was ended.

=== 417 YW ===
* Ending years of strife and division, Garard I seizes the throne and becomes king of Wesnoth, beginning the [[Garardine Dynasty]].

=== 440 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Garard_II Crown Prince Garard II] is born.

=== 442 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Delfador Delfador], later called "the Great", is born.

=== 450 YW ===
* Prince Arand is born.

=== 468 YW ===
* Zorlan becomes Great Chief of the northern orcs
* [http://wiki.wesnoth.org/CharactersStorys#Delfador Delfador] graduates from the Great Academy. [http://wiki.wesnoth.org/Mainline_Campaigns#Delfador.27s_Memoirs '''Delfador's Memoirs'''] begins.

=== 470 YW ===
* Garard I dies; [http://wiki.wesnoth.org/CharactersStorys#Garard_II Garard II] ascends to the throne of Wesnoth
* Orcs under Great Chief Zorlan and undead raised by the necromancer [http://wiki.wesnoth.org/CharactersStorys#Iliah-Malal Iliah-Malal] raid Wesnoth's borders. All but the first and the last three scenarios of [http://wiki.wesnoth.org/Mainline_Campaigns#Delfador.27s_Memoirs'''Delfador's Memoirs''' ] take place in this year.
* Control of the Estmarks is effectively lost during this war, not to be regained for decades. Outposts are built on the near side of the Weldyn to repel orc raids. The long watch of the River Guard begins.

=== 478 YW ===
* Garard II marries Asheviere.
* Garard issues the Edict of the Sceptre, providing that the crown shall settle after his death on whichever member of the royal family successfully retrieves it from the Caverns of Flame.

=== 480 YW ===
* Crown Prince Eldred is born.

=== 483 YW ===
* Erain and Ethyn, identical twins and brothers of Eldred, are born.

=== 498 YW ===
* Princess Li'sar is born.

=== 500 YW ===
* Prince Konrad is born, the youngest of several sons of Prince Arand.
* Wesnoth and the orcs of the north go to war.

=== 501 YW ===

===== Betrayal on the battlefield =====
* Garard leads his army to orc encampment at Galcadar by the Ford of Abez.
* Garard's forces split into two groups, one led by himself and the other by his son Eldred.
* Eldred betrays his father and attacks him with the troops under his control.
* Eldred slays King Garard and his uncle Prince Arand on the battlefield of Abez.

===== Reprisal =====
* Delfador escapes the battle and heads to Weldyn.
* Eldred gives tribute to the Orcish king, who stops his attacks.
* Delfador gathers a force of Loyalists to avenge Garard's Death.
* Eldred's forces confront Delfador's Loyalists at Weldyn.
* The Loyalists are defeated, but Eldred is slain by Delfador in the fight.

===== Asheviere seizes power =====
* Asheviere orders the slaughter of Garard's nephews and declares herself Queen of Wesnoth.
* Hearing of the news Delfador infiltrates the palace.
* Delfador finds the youngest prince Konrad as he is slain.
* Delfador flees, taking Konrad's body for burial to the land of the Elves.
* While traveling through Wesnoth, Elf Lady Parandra finds an orphaned human child.
* Parandra and Delfador agree to give the orphan the identity of Prince Konrad.
* Delfador and Konrad flee to live in refuge with the Wood Elves of the great southwestern forest.

===== The country resists Asheviere =====
* Elensefar refuses to submit to Asheviere and declares itself an independent city-state.
* After several defeats, Wesnoth's army retreats from the remote areas of the kingdom. The western Wesnothian border recedes, is fixed, and remains heavily defended.
* As a result of the loyalist withdrawal, several small human communities on the west coast of the Great Continent live in relative independence while elves flourish in the great forest to the southwest of Wesnoth.
* A band of Wesnoth citizens organizes resistance to Asheviere's siezure of power. They are eventually forced to abandon their home and settle in the Three Sisters ('''Liberty''').

=== 502-517 YW ===
* Delfador raises Konrad under the protection of the Elves.

=== 517 YW ===
* Asheviere hires Orcish forces to hunt down her nephew-in-law Konrad.
* Orcish forces converge on Delfador's refuge.
* Konrad flees his home with the elves and embark upon a quest to regain the throne of Wesnoth. '''Heir To The Throne''' begins.

=== 518 YW ===
* Konrad crosses the Great River into the Northlands on a search for the Sceptre of Fire.
* They enter the Caves of Knalga, allied with Princess Li'sar, and find it.
* They return to Wesnoth and claim the throne. '''Heir to the Throne''' ends.

=== 522 YW ===
* Birth of Princess Ana'sar.

=== 530 YW ===
* Wesnothian colonists begin reclaiming the Estmarks.

=== 544 YW ===
* With both sides of the lower Weldyn River again civilized territory, the River Guard posts south of Soradoc are abandoned. Wesnothian military activity shifts eastward into the Estmarks.

== 530-630 YW: The Age of Fear ==
The Age of Fear takes its names from the events of the end of the era. On the surface, the first 77 years were very uneventful for the kingdom of Wesnoth. However, during this time unexplainable magical events took place, especially in the eastern lands. Previously tamed lands were slowly claimed by wilderness as fear and paranoia gradually overshadowed the spirit of pioneering and adventure displayed earlier in Wesnoth's history. In the last 10 years of the age, Wesnoth bore the brunt of the most powerful Undead attack ever and was nearly destroyed. By the end of the era, most of Wesnoth had been made barren, most of the great buildings inside and outside of Weldyn were razed, and the population of Wesnoth was half of what it had been.

It was in this era that certain areas of the chaotic Northlands were for the first time put into any kind of law and order. A small group of humans and dwarves, accepting anyone of any race who wished to join, formed themselves into the "Northern Alliance”, with the vision of making the Northlands safe to live in. Over time, this alliance grew slowly but steadily in power. By the end of the era, the alliance had succeeded in making a few small areas, including Knalga and the surrounding regions, stable and prosperous. Consequently, many people evacuated from the wasteland that most of Wesnoth had become and moved north - depleting the population of Wesnoth still further.

=== 533 YW ===
* Delfador succumbs to old age and dies, his body is entombed alongside his staff in Eregonor.
* The next great sage of Wesnoth, [http://wiki.wesnoth.org/CharactersStorys#Dacyn Dacyn], is born.

=== 534 YW ===

* The small community of Dwarven Doors, in the Northlands just outside Knalga, rebels against the Orcish overlords. '''Northern Rebirth''' begins.
* The residents, led by Tallin, head underground and find dwarves, whom they ally with.
* Their combined forces destroy a lich who is attempting to claim Knalga as his own.
* Abhai finds the [http://wiki.wesnoth.org/CampaignDialogue:NR#Abhai_Finds_Rod_of_Justice Rod of Justice]

=== 535 YW ===

* The warlord-aspirant Rakshas attacks Tallin and his forces, but does not penetrate the dwarves' defences.
* To help defeat the orcs, Tallin secures the help of two Liches, and rescues an elvish princess to secure the help of the elves.
* Assisted by his new allies, Tallin smashes the forces of Rakshas.
* According to some historians, Tallin and the elvish princess are married; others say they parted in bad blood.
* To preserve the new-found peace in the Northlands, Tallin and his allies form the Northern Alliance. '''Northern Rebirth''' ends.

=== 550 YW ===

* Lord Hamel of Knalga sends an expedition to Kal Kartha to determine the fate of the Hammer of Thursagan ('''The Hammer of Thursagan''' takes place in late 550 YW to early 551 YW.).
* Dwarves at Knalga and elsewhere begin to reclaim the lost art of runesmithing.
* Wesnothian colonization expands southward past Fort Tahn.

=== 563 YW ===
* Konrad and Li'sar die after an extraordinarily long reign.
* Princess Ana'sar becomes queen.
* The seer Galdren becomes prominent at the court of Weldyn.

=== 585 YW ===
* Queen Ana'sar retires.
* Haldric VII becomes king of Wesnoth.

=== 589 YW ===
* Dacyn the White Mage and Ravanal, an eastern wizard, compete to be the king's advisor.
* The seer Galdren dies after advising Haldric VII to choose Dacyn.
* The king does as Galdren advises.

=== 593 YW ===
* Ravanal reveals that he has turned to evil, and flees from Weldyn.
* Konrad II is born.
* Certain southern frontier regions are formally annexed to the Kingdom of Wesnoth as the Province of Kerlath.

=== 598 YW ===
* South Guard organized as a semi-detached formation of the Royal Army, to protect the inhabitants of the frontier province of Kerlath.

=== 607 YW ===
* South Guard ceases reporting. Haldric VII sends Deoran, grandson of Haldiel, to investigate. '''The South Guard''' takes place in 607-608 YW.

=== 612 YW ===
* Haldric VII dies. Konrad II is crowned King of Wesnoth.
* Dacyn continues his duties as advisor with Konrad II.

=== 625 YW ===
* Mysterious disappearances of livestock and peasants cause partial evacuation of the the '''Estmark Hills'''. Lords of the Horse Plains report increased banditry from there.
* Konrad II sends [http://wiki.wesnoth.org/CharactersStorys#Dacyn Dacyn] with [http://wiki.wesnoth.org/CharactersStorys#Owaec Owaec] and [http://wiki.wesnoth.org/CharactersStorys#Gweddry Gweddry] to man the old River Guard strongpoints. [http://wiki.wesnoth.org/Mainline_Campaigns#The_Eastern_Invasion '''Eastern Invasion'''] begins.

=== 626 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Mal-Ravanal Mal-Ravanal] attacks the middle outpost where [http://wiki.wesnoth.org/CharactersStorys#Gweddry Gweddry] and [http://wiki.wesnoth.org/CharactersStorys#Dacyn Dacyn] are stationed.
* Dacyn and Gweddry travel to the northern outpost, and, with [http://wiki.wesnoth.org/CharactersStorys#Owaec Owaec], retreat into the northlands.
* In the Far North, the wife of Kai Laudiss slain in a large raid by the orcs of Tirigaz on Jotha
* Kai Laudiss slain by poisoned orcish dart during failed attack on the Port of Tirigaz orcs. His son, [http://wiki.wesnoth.org/CharactersStorys#Kai_Krellis Krellis] succeeds him as Kai and relies on the wisdom of [http://wiki.wesnoth.org/CharactersStorys#Cylanna Cylanna], a priestess.
* The merfolk city of Jotha is overrun by undead (Mal Kevek and others). The action of [http://wiki.wesnoth.org/Mainline_Campaigns#Dead_Water '''Dead Water'''] takes place.

=== 627 YW ===
* Wesnoth's last defences are broken and the undead march on Wesnoth
* In the northlands, the orcs drive [http://wiki.wesnoth.org/CharactersStorys#Gweddry Gweddry's] army back across the river.
* Weldyn is besieged.
* Gweddry breaks through undead lines to reach Weldyn and a council is held.
* Gweddry's army is fortunate and kills [http://wiki.wesnoth.org/CharactersStorys#Mal-Ravanal Mal-Ravanal]. [http://wiki.wesnoth.org/Mainline_Campaigns#The_Eastern_Invasion '''Eastern Invasion''' ] ends. [http://wiki.wesnoth.org/Mainline_Campaigns#Dead_water '''Dead Water'''] ends (about this time).
* Wesnoth is saved, but large portions have been laid waste by the undead.
* After destroying [http://wiki.wesnoth.org/CharactersStorys#Mal-Ravanal Mal-Ravanal's] henchmen the mermen relaxed and began rebuilding in earnest, and soon Jotha was restored.

== 628-673 YW: The Silver Age of Wesnoth ==

The Silver Age, or restoration of the Wesnothian kingdom, essentially coincides with the rest of the long and successful reign of [http://wiki.wesnoth.org/CharactersStorys#Konrad_II Konrad II]. During this period Wesnoth largely recovered from the damage that Mal-Ravanal's undead attack had done. It would, however, never quite regain the majesty it had at the height of its power.

The Northlands, aided by a second wave of colonization north from Wesnoth, become more civilised and stable. Although nowhere near as prosperous as Wesnoth was during its Golden Age, the Northlands developed towns of significant size and a thriving - if somewhat dangerous - trade network.

Four major powers soon came to dominate much of the Northlands. First there were the dwarves, who controlled most of the mountains and a vast array of underground tunnels and caverns. To the east, shrouded in mystery, lay the Elvish forests which continued to be inaccessible to anyone not of elvish blood. The remaining landscape was dominated either by orcish tribes, or independent human earldoms. As competition for the land grew fierce, wars smoldered between human and orcish forces.

=== 628-635 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Konrad_II Konrad II] begins his attempt to rebuild Wesnoth.

=== 673 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Konrad_II Konrad II] dies, bringing the [[Garardine Dynasty]] to an end. Second Wesnothian civil war begins.

== 786-826 YW: The Legacy of Black-Eye Karun ==

After decades of struggle, Black-Eye Karun becomes the first warlord since the assassination of Great Chief Brurbar in 20 YW to unite all the different squabbling orcish tribes under his banner. Among his many accomplishments as a Sovereign, his most famous is the creation of the Great Council.

Karun was a far-sighted individual and he knew that after his death the orcish tribes would once again turn to fighting among themselves, with little he could do to prevent that and consequent peril from the Wesnothians and elves.

Consequently, Karun selected from among all the different tribes six of the most sober and wisest orcs and thus created the Great Council. It was the Great Council's job to stay aloof from any tribal or territorial squabbling amongst the orcs, but yet always remain there to give advice to whomever came to seek it. In order to preserve the orcish race in the event of an emergency, he invested in them the power to call up The Great Horde. It was established that every orc, no matter what tribe he came from, must obey the summons of The Great Horde and follow wholeheartedly the leader that the Great Council put at the head of The Great Horde.

===786 YW===
* Karun is born.

===805 YW===
* Karun devised the formation of the Great Council.

===811 YW===
* A border dispute between Karun and a human enclave aligned with the Northern Alliance leaves several men and orcs dead and begins a feud that will grow into a fifteen-year war.

===812 YW===
* Rahul I becomes Lord Protector of the Northern Alliance.

===816 YW===
* [http://wiki.wesnoth.org/CharactersStorys#Kapou.27e Kapou’e] is born

===826 YW===
* Rahul I (Lord Protector of the Northern Alliance) and Black Eye Karun sign a peace treaty ending a 15 year war between the humans and the orcs. Soon after this Karun, is ambushed and killed in mysterious circumstances.

===829 YW===
* Frustrated by the fallout of Karun's supposed assassination, Rahul I resigns, and Howgarth III takes his place as Lord Protector.

===842 YW===
* Famine in the Northlands. Famine led humans to colonize some orcish lands and push orcs into desolated hill country. The few orcish tribes who had remained part of the Alliance, feeling the pressure, either left Alliance territory or revolted and were destroyed.
* Retaliating, the orcs systematically slaughtered human colonies and villages on their lands. Then, Earl Lanbec'h — the most powerful human warlord of the North — determined to abolish the orcish menace raised an army and conferred leadership of it to his son-in-law Baron Alber.
* In response, the Great Council set up by the Black Eye Karun calls upon The Great Horde and bestows leadership of it upon [http://wiki.wesnoth.org/CharactersStorys#Kapou.27e Kapou’e]; [http://wiki.wesnoth.org/Mainline_Campaigns#Son_of_the_Black_Eye '''Son of the Black Eye'''] begins.

===843 YW===
* Half of the Great Council is treacherously slain by the allied human forces and orcish unity disintegrates. Faced with the extermination of all the orcs on the Great Continent, [http://wiki.wesnoth.org/CharactersStorys#Kapou.27e Kapou’e] forcibly asserts his control over the orcish territories and defeats the enemy forces. The Northern Alliance arrives on the scene in time for the final battle and helps Kapou’e defeat the forces of the northern earldoms, who had broken the treaty. Kapou’e then assumes the position of Sovereign over the northern tribes, and his rule ushers in an unprecedented era of unity and prosperity for the orcs.
* After 843: Portions of Kapou'e's army act as mercenaries in foreign struggles with other races which keeps them from attacking their nearest neighbors.

===852 YW===
*[http://wiki.wesnoth.org/CharactersStorys#Kapou.27e Kapou’e] repels a large elvish invasion.

===858 YW===
* The humans once again stage an invasion but prove to be no match for the united orcish forces under the leadership of [http://wiki.wesnoth.org/CharactersStorys#Kapou.27e Kapou’e]. [http://wiki.wesnoth.org/Mainline_Campaigns#Son_of_the_Black_Eye '''Son of the Black Eye'''] ends.

==After the Great Fall==
At some unknown point in the future, an unspeakable cataclysm scorched the surface of the lands and the God-Demon Zhangor terrorize the world. The Wesnoth magicians try to raise up a 3rd sun in the sky, Gaia, but they fail and the 'sun' falls down over Weldyn. The capital is no more. The King and his family are dead and there is no heir. The local leaders tear apart Wesnoth. The nights become longer, days hotter. Evil creatures show up. Forests die, hills turn into rocky wastelands and fields become barren deserts. In the apocalypse allies turn against each other and friends fight over what few resources remain. The great nations were destroyed, and huge numbers of people died. Still amidst the chaos somehow small groups of people survived, sheltered in hidden places. In this post-apocalyptic world survival is a daily struggle as a few remaining tribes eke out an existence among the ruins of fallen empires. Heroic bands of elves, nomadic refugee humans, savage hordes of orcs and dark necromancers all forge new lives under the merciless dual suns, Sela and Naia, of this new Irdya. In the meantime an evil entity named Uria arises, scarring the history for life.

===??? Post-Wesnoth===

* The Quenoth elves adapt to life in barren world of the Great Southern Desert. Over time they lost their affinity for the woodlands of their ancestry and embrace life in the sandy wastelands.
* Under the leadership of Tanuil, the Quenoth elves build and sustain a fortified village around a rare oasis. The village thrives amidst the hostilities of the desert.
* One night, a meteor storm rains from the sky and destroys the village of the Quenoth elves. '''Under the Burning Suns''' begins. The next day, Tanuil, like many others, is missing and presumed dead. Kalehssar (Kaleh), nephew of Tanuil, takes leadership of the remaining Quenoth elves as the surviving next of kin.
* Kaleh, heeding the voice of his god Eloh in his dreams, gathers the remaining Quenoth elves and leads them north to a new promised land, foregoing rebuilding of their desert village.
* The Quenoth elves battle their way north through Undead, Orcs, Bandits and other evil, venturing underground beneath a large mountain range at the command of Eloh.
* Befriending unexpected allies underground, Kaleh's forces survive to the other side of the mountain.
* Keratur, son of Tanuil and survivor of the cataclysm, insane with fright attacks Kaleh. Kaleh defeats Keratur.
* Kaleh defies commands given him by a vision of Eloh.
* The Quenoth reach the ocean. Aided by Merfolk, they escape the mainland and head for a newly discovered island, a place where the Quenoth may settle in peace.
* On the island, the Quenoth confront Yechnagoth, the Eater of Souls and impersonator of Eloh. Yechnagoth and army are destroyed by the Quenoth.
* Kaleh and the elves settle on their newfound, and newly named, Quenoth Isle. '''Under the Burning Suns''' ends.

== History Credits ==

* Timelined by Kamahawk and Turin. Revised to incorporate material from later version of Legend of Wesmere and reconcile different versions of the history of the Sceptre of Fire by Eric S. Raymond.

* History derived from:
** Eastern Invasion
** Heir to the Throne
** Legend of Wesmere
** Liberty
** Northern Rebirth
** The Hammer of Thursagan
** The Rise of Wesnoth
** Under the Burning Suns
** Dead Water
** Delfador's Memoirs

* Setting details derived from:
** Invasion from the Unknown

== See Also ==

* [[Geography of Wesnoth]]
* [[Poetry of Wesnoth]]
* [[Races]]
* [[FactionHistory]]
* [[Future History]] '''(unofficial)'''

[[Category:World of Wesnoth]]
[[Category:History]]

GettextForWesnothDevelopers

2022-07-19T23:58:56Z

Name: Fixed wmlxgettext syntax based on: https://github.com/wesnoth/wesnoth/pull/6875#issuecomment-1188052805

This page is used to help Wesnoth developers and UMC authors to work with the internationalization (i18n) system, based on GNU gettext.

== General design of gettext use ==

Programs using Gettext include the strings in one language (usually English) within the source code. For each target language, a separate file provides a look-up table from English to that language. If the file is missing or doesn't have a translation for that string, the system falls back to using the English text.

The translation mechanism usually involves a function or macro called ''_'' (a single underscore sign). Examples are in the programming-language specific sections below.

=== Textdomains ===

Gettext splits translations into domains. For Wesnoth, the general idea is to use distinct textdomains for each campaign or add-on, so that UMC authors can easily ship translations together with their campaigns. These domains are covered in more depth in [[GettextForTranslators]].

The convention is to name each domain using the name of the add-on, or just its initials. For example, ''wesnoth-utbs'' or ''wesnoth-Son_of_Haldric''. For UMC, it probably makes sense to use the full name to ensure that it doesn't clash with another add-on.

=== Caret hints ===

Some strings look the same in English but should not necessarily look identical in translations. To handle this, those strings can be prefixed with any descriptive string and a '''^''' character. For users viewing in '''en_US''', these hints will be automatically removed from the string before showing it to the user.

{{DevFeature1.15|2}} if the string contains more than one '''^''', the descriptive string ends at the first '''^''', everything following the first '''^''' will be shown to the user.

{{DevFeature1.15|18}} When using gettext's Plural Forms, these prefixes can and should be used in both the singular and the plural.

=== UTF-8 ===

For translation, all C++, WML and Lua files should be in UTF-8. As noted in the [[Typography_Style_Guide]], some punctuation should be used that's outside of the ASCII subset.

== Marking up strings in C++ ==

In C++, you can mark up strings for translations using the <syntaxhighlight lang=c++ inline>_("A translation")</syntaxhighlight> and <syntaxhighlight lang=c++ inline>_n("Translation", "Translations", int)</syntaxhighlight> macros. The <code>_n</code> macro is to be used if the string has a singular and plural form.

You can also add comments for translators. Single-line comments must start with <code>TRANSLATORS:</code> and be on the line ''immediately'' above the translatable string. For multi-line comments, the <code>TRANSLATORS:</code> only needs to be on the first line to include the whole comment, and the last line must be immediately above the translatable string.

If the string contains any placeholders, '''don't''' use <code>snprintf</code>. Instead use WML style variables, put their values in a <syntaxhighlight lang=c++ inline>utils::string_map</syntaxhighlight> and use the <code>VGETTEXT</code> or <code>VNGETTEXT</code> macros instead.

<syntaxhighlight lang=c++>
utils::string_map symbols;
symbols["enemies"] = std::to_string(enemy_count_);
symbols["friends"] = std::to_string(friend_count_);
std::string message;
if ( friend_count_ != 0 && enemy_count_ != 0 ) {
// Omitted from the example - see the code in src/action/move.cpp for how to handle strings with two independent ints.
} else if ( enemy_count_ != 0 ) {
// TRANSLATORS: Only enemies sighted -- bad message.
// This is shown when a move is interrupted because units were revealed from the fog of war.
message = VNGETTEXT("Enemy unit sighted!", "$enemies enemy units sighted!", enemy_count_, symbols);
} else if ( friend_count_ != 0 ) {
// TRANSLATORS: Only friends sighted -- good message.
// This is shown when a move is interrupted because units were revealed from the fog of war.
message = VNGETTEXT("Friendly unit sighted", "$friends friendly units sighted", friend_count_, symbols);
}
</syntaxhighlight>

The <syntaxhighlight lang=c++ inline>string_map</syntaxhighlight> can contain additional values that aren't used in the translated string. In the example above, it has both ''friends'' and ''enemies''.

By default, all strings in C++ belong to the "wesnoth" textdomain. If a different textdomain is required, you can add a textdomain binding at the top of the source file, before any include statements. A textdomain binding looks like this: <syntaxhighlight lang=c++>#define GETTEXT_DOMAIN "wesnoth-lib"</syntaxhighlight>

You should avoid placing translatable strings in C++ headers if at all possible. Though there are a few places where it may be unavoidable, such as if templates are in use, it creates the risk of the strings sometimes being looked up in the wrong textdomain if the header is included in multiple files with different textdomains. If possible, always factor the translatable strings out into a source file.

== Marking up strings in WML ==

=== The textdomain bindings ===

All files with translatable strings must declare which textdomain they use, which is normally done by putting ''#textdomain'' on the first line of each .wml file. See the example below:

<syntaxhighlight lang=wml>
#textdomain wesnoth-Son_of_Haldric

[unit_type]
id=Mu
name= _ "Mu"
# ...
[/unit_type]
</syntaxhighlight>

Note that it is highly recommended that the first textdomain binding be on the first line of the file. Otherwise, odd stuff may happen.

=== The translatable strings ===

To mark a string as translatable, just put an underscore ( _ ) in front of the string you wish to be marked as translatable, like the example below:

<syntaxhighlight lang=wml>
name= _ "Mu"
</syntaxhighlight>

==== Notes to the translators ====

If you think a translatable string needs additional guidance to be translated properly, you can provide a special comment that will be seen by the translators. Some hints are generated automatically, but in general if you have to wonder whether a hint is needed then it probably is. The context of the scenario isn't obvious in the translation tools, and you can't assume that the strings are shown to the translator in the same order that they appear in the WML file.

Just begin the comment with '#po:' or '# po:' above the string in question. This must be on the line (or lines) immediately before the string that the hint applies to:

<syntaxhighlight lang=wml>
#po: "northern marches" is *not* a typo for "northern marshes" here.
#po: In archaic English, "march" means "border country".
story=_ "The orcs were first sighted from the north marches of the great forest of Wesmere."
</syntaxhighlight>

The wmlxgettext tool will automatically generate hints for some tags, in addition to hints from '# po:' comments:

* For ''[message]'': the ''id'', ''speaker'', ''role'' or ''type'' used to choose the speaker
* For ''[object]'': the ''id''
* For ''[unit]'': the ''id'' and ''unit_type''
* For ''[unit_type]'': the ''id'' and ''race''
* For ''[objective]'': whether it's ''condition=win'' or ''condition=lose''

==== Things to avoid ====

Note that there are certain things you should never do. For example, '''never''' mark an empty string as translatable, for wmlxgettext (the tool that extracts strings from WML) will abort upon detecting one. Therefore, what is seen below should never be done:

<syntaxhighlight lang=wml>
name= _ ""
</syntaxhighlight>

Also, never put macro arguments in a translatable string, for it will not work. The reason for this is that the preprocessor does its job before gettext, thus gettext will try to replace a string that does not exist. Therefore, what is shown below should not be done:

<syntaxhighlight lang=wml>
name= _ "{TYPE} Mu"
</syntaxhighlight>

To show why it will not work:

<syntaxhighlight lang=wml>
#define UNIT_NAME TYPE
name= _ "{TYPE} Mu"
#enddef

{UNIT_NAME ( _ "Sword")}
{UNIT_NAME ( _ "Bow")}
</syntaxhighlight>

Translation catalogues would have this: "{TYPE} Mu", therefore gettext will look for it even though it will not exist because we, in fact, have these after the preprocessor is done:

<syntaxhighlight lang=wml>
name= _ "Sword Mu"
name= _ "Bow Mu"
</syntaxhighlight>

Since those are not in the catalogues, they will not get translated.

=== Gender-specific strings ===

Several tags, including ''[message]'', ''[abilities]'' and ''[trait]'', can choose different strings based on the gender of the unit. In English the two versions are likely to be the same, but other languages may have gender-specific words for 'I' or 'me'.

<syntaxhighlight lang=wml>
[message]
speaker=student
message= _ "Have you found an orc for me to fight, huh? A troll?"
female_message= _ "female^Have you found an orc for me to fight, huh? A troll?"
[/message]
</syntaxhighlight>

The convention in WML is, as above, to use ''message='' and ''female_message='', with the latter string including the prefix ''female^''. The mechanism also supports ''male_message='', but all units will fall back to using the plain ''message='' value if there isn't gender-specific version that matches their gender.

The message is chosen based on the gender of the speaking unit. To change the message based on the gender of another unit requires separate ''[message]'' tags:

<syntaxhighlight lang=wml>
[if]
[have_unit]
id=student
gender=male
[/have_unit]
[then]
[message]
speaker=Delfador
message= _ "Young man, you have $student_hp hitpoints and a sword. I’m fairly sure you’ll win."
[/message]
[/then]
[else]
[message]
speaker=Delfador
message= _ "female^Young lady, you have $student_hp hitpoints and a sword. I’m fairly sure you’ll win."
[/message]
[/else]
[/if]
</syntaxhighlight>

Using a macro to encapsulate most of that can be useful. The example above is from the tutorial, after expanding the ''GENDER'' macro which is defined in data/campaigns/tutorial/utils/utils.cfg.

=== Proper nouns in strings ===

Some languages require declensions of proper nouns - a person's name may change slightly depending on their role in a sentence. See for example [https://github.com/hrubymar10/wesnoth-cs/pull/209#issuecomment-1066163433 the Czech translators' PR 209].

Where there are a small number of units that might be addressed, for example the two in the tutorial or the four possible allies in UtBS, it's better to have a separate translatable string for each possible character instead of interpolating '''$unit.name''' into a string.

=== Reusing mainline translations ===

You can reuse translations for strings in mainline domains by using multiple textdomain bindings:

<syntaxhighlight lang=wml>
# textdomain wesnoth-Son_of_Haldric

[unit_type]
id=Mu
name= _ "Mu"
# ...

[attack]
id=sword
#textdomain wesnoth-units
description= _ "sword"
# ...
[/attack]

#textdomain wesnoth-Son_of_Haldric
# ...
[/unit_type]
</syntaxhighlight>

Of course, if you use bindings for multiple textdomains, make sure the right parts of the file are bound to the right domains. Also, never try to use the mainline campaigns’ domains, for there is no guarantee that the mainline campaigns will be available on all setups. So, only use the core domains: wesnoth, wesnoth-editor, wesnoth-lib, wesnoth-help, and wesnoth-units.

==== The gettext helper file ====

A gettext helper file is a lovely file that makes reusing mainline translations nice and easy, by having all strings that should use a specific textdomain in a single file. It is also more wmllint-friendly.

Here is an example of a gettext helper file. The macro names start with 'SOH_' to ensure that they don't clash with another add-on's macros (assuming that this add-on is Son_of_Haldric).

<syntaxhighlight lang=wml>
#textdomain wesnoth-lib

#define SOH_STR_ICE
_"Ice" #enddef

#textdomain wesnoth-units

#define SOH_STR_SWORD
_"sword" #enddef
</syntaxhighlight>

A typical name for gettext helper files is ''mainline-strings.cfg''.

To use it, just wire it into your add-on and use the macros:

<syntaxhighlight lang=wml>
[attack]
id=sword
name={SOH_STR_SWORD}
# ...
[/attack]

[terrain_type]
id=ice2
name={SOH_STR_ICE}
# ...
[/terrain_type]
</syntaxhighlight>

=== Unbalanced WML macros ===

WML macros can be ''unbalanced'', meaning that they either include a [tag] without the corresponding [/tag] or a [/tag] before the corresponding [+tag]. These macros are expected to be used in a place where the [tag] is already open. Writing new macros using this isn't recommended; instead please ask in the WML Workshop forum about better ways to do it.

When generating the .pot files for translation, wmlxgettext may stop with one of the errors
* error: Son_Of_Haldric/utils/abilities.cfg:29: unexpected closing tag '[/abilities]' outside any scope.
* error: Son_Of_Haldric/utils/abilities.cfg:300: End of WML file reached, but some tags were not properly closed. (nearest unclosed tag is: [abilities])

Suppose abilities.cfg line 29 is in the definition of SOH_ABILITY_BLITZ. To get the .pot file generated, the simplest change is to use ''# wmlxgettext'' comments to add the missing opening or closing tags:

<syntaxhighlight lang=wml>
# wmllint: unbalanced-on
# wmlxgettext: [abilities]
#define SOH_ABILITY_BLITZ
[dummy]
id=soh_blitz
# ... ability definition stuff ...
[/dummy]
[/abilities]
# ... several lines of code, none of which are an ''#enddef'' ...
[+abilities] # wmlxgettext: [/abilities]
#enddef
# wmllint: unbalanced-off
</syntaxhighlight>

== Marking up strings in Lua ==

In Lua code, textdomains are a callable object that looks up a string. This has support for both singular and plural strings. By convention, the name <code>_</code> is usually used for the textdomain object.

The following sample code demonstrates how to fetch translatable strings in Lua:

<syntaxhighlight lang=lua>
local _ = wesnoth.textdomain "wesnoth"

-- Look up a normal string:
local win_condition = _ "Defeat enemy leader(s)"

-- Hints for the translators start with "po:", as in WML:
-- po: Floating text shown when a unit with the "feeding" ability gets a kill
local text = stringx.vformat(_"+$value max HP", { value = feeding.value})
</syntaxhighlight>

Plural strings are supported since Wesnoth 1.14:
<syntaxhighlight lang=lua>
local turn_count = 5
turn_counter = _("this turn left", "%d turns left", turn_count)
turn_counter = tostring(turn_counter):format(turn_count)

-- For readability, the example's strings are slightly different to the real code.
-- The real strings have brackets in the text shown to the player.
</syntaxhighlight>

In Wesnoth 1.15, variables can be interpolated using names:
<syntaxhighlight lang=lua>
-- Look up a plural string, using the preferred style (as of Wesnoth 1.15.3):
local turn_count = 5
turn_counter = _("this turn left", "$remaining_turns turns left", turn_count)
turn_counter = turn_counter:vformat{remaining_turns = turn_count}
</syntaxhighlight>

== The textdomain tag ==

To tell the engine where to search for the .po and .mo files, each textdomain needs a ''[textdomain]'' tag. For add-ons and mainline campaigns, the tag is usually placed inside of the _main.cfg. This is a top-level tag, so should be outside the ''[campaign]'' or ''[modification]'' tag.

Translatable strings from C++ and Lua use the same textdomains as WML; this WML tag tells the engine where to search for these strings irrespective of which programming language the string appeared in.

<syntaxhighlight lang=wml>
[textdomain]
name="wesnoth-Son_of_Haldric"
path="data/add-ons/Son_of_Haldric/translations"
[/textdomain]
</syntaxhighlight>

The .po (or .mo) files will be loaded from a subdirectory of the ''translations'' directory.

== Generating the .pot and .po files for UMC ==

For each language, Wesnoth will search for a .po file containing the translations. How to create that file will be explained below, but first the overview of where it should go. Continuing with the Son of Haldric example, the Swedish translation would be in the file:

* ''data/add-ons/Son_of_Haldric/translations/wesnoth-Son_of_Haldric/sv.po'' .

That comes from:

* ''data/add-ons/Son_of_Haldric/translations'' comes from the ''[textdomain]'' tag's ''path''
* ''wesnoth-Son_of_Haldric'' is the textdomain's name
* ''sv'' is the language code for Swedish. The codes for each language are given in the big table on [https://www.wesnoth.org/gettext/ https://www.wesnoth.org/gettext/] .

Wesnoth 1.14 (but not 1.12) supports reading .po files directly, so when you add the .po file and the new translation should appear as soon as you refresh the cache.

=== Generating the .pot file ===

The template (.pot) file contains all of the strings that need to be translated in the .po files, but without the translations.

The .pot is generated from WML and Lua files using a tool called wmlxgettext. With Wesnoth 1.14.5 and later, this is shipped with Wesnoth itself as part of the [[Maintenance_tools]] and can be used from the Maintenance Tools' GUI. At the moment it's not documented on that page, but if you follow the instructions to get GUI.pyw running then you'll see there's a wmlxgettext tab.

Pre-1.13 instructions on how to get and use it are in Nobun's [https://r.wesnoth.org/p617733 forum posting].

==== Error messages from wmlxgettext ====

If you get the error from ''wmlxgettext'' of "UTF-8 Format error. Can't decode byte 0x91 (invalid start byte).", and the line in question has a curly quotation mark, that likely means that your text editor is using the Windows-1252 character set, and you need to replace the Windows quotes with their Unicode equivalents, see [[Typography_Style_Guide]] and your editor's documentation for more info. The same applies if the error message says 0x92, 0x93 or 0x94.

If you get either "unexpected closing tag '[/''something'']' outside any scope" or "End of WML file reached, but some tags were not properly closed. (nearest unclosed tag is: [''something''])" then see [[#Unbalanced_WML_macros]] above.

=== Generating the .po files for each language ===

Each .po file can start as a simple copy of the .pot file. Either the author or the translator copies the template to the language-specific filename, and then the work of [[GettextForTranslators]] happens on those copies.

Some .po editors, for example poedit, will recognise that the .pot is a template, and automatically suggest saving to a different filename. The poedit editor can also update a .po file based on changes to the .pot file.

=== Generating the .mo files for UMC ===

For Wesnoth 1.14, it's generally not necessary to compile the .po files to .mo files. The mainline translations still use .mo files for better performance, but UMC authors can skip the .mo compilation stage.

== See Also ==

* [[WesnothTranslations]]
* http://www.gnu.org/software/gettext/
* [https://www.gnu.org/software/gettext/manual/html_node/Preparing-Strings.html#Preparing-Strings GNU gettext manual on preparing translatable strings]
* [[GetText]]
* [https://wmlxgettext-unoff.readthedocs.io/en/latest/ wmlxgettext documentation]

[[Category:Development]]

Winds of Fate

2022-01-21T05:54:09Z

Name:

== Introduction ==

This is the walkthrough for the mainline drakes campaign, '''Winds of Fate'''. It was formerly known as '''Wings of Victory''' or '''Wings of Valour'''. It is a hard level campaign with 11 scenarios and 4 levels of difficulty (Normal/Challenging/Difficult/Nightmare).

=== Synopsis ===
''The story of how the drakes first arrived on the Great Continent.''

'''Note: This walkthrough has many spoilers. Read at your own discretion.'''

== General Strategy ==

In this campaign, the player will have access to all recruits of the MP Default Era's '''Drakes''' faction, but not all at once. Most of the recruit list will unlock with story progression and some unit-trees might be temporarily unavailable due to story reasons. With that being stated, I would suggest prioritizing on the following:

* Get a '''Drake Flare''' and advance him to a '''Drake Flameheart'''. The Leadership ability has predominant value in this campaign as you will mostly be suffering losses throughout since Drakes will mostly get 20%-40% defense on most of the maps (with the exception of the Glider caste, whose defenses range from 30-50). Thus, having a Flameheart to coordinate the attacks of level 2 and level 1 Drakes and Saurians will be paramount to this campaign.
* '''Reshan''': This hero-class '''Drake Glider''' will be available for the nine out of the eleven scenarios. Having him advance early to Sky Drake and later to Hurricane Drake is advised. He can be valuable as both a scout and a mixed-fighter.
* '''Gorlack''': The protagonist. He starts at level 1 as a '''Drake Burner'''. He is the only Drake Burner in this campaign to be able to advance to the fearsome and devastating '''Armageddon Drake'''. Feeding him XP should be one of the main focus points of any player of this campaign. Do not worry about any XP deficiency for other units. You will have plenty of chances to farm experience points.
* Saurian Oracles and Saurian Soothsayers. Having these units will benefit you greatly, especially in the last scenario.
* Drake Blademasters. Drake Fighter recruitment is available onwards from scenario 2. Levelling them is recommended as they can dish out big damage during the day, are fast and deadly.
* Drake Arbiters and Wardens. The scenario designs do not really favor the Drake Clasher caste but you can recruit level 2 drakes and saurians at the very end of the campaign so just try to have 2 or 3 arbiters on hand. Drake Thrashers are not that useful in any of the scenarios.
* Fire and Inferno Drakes. These are probably what should be filling your recall list, second only to Drake Warriors and Blademasters. Throughout the campaign, these units will be your main source of damage during the day time schedules.
* Most of the scenarios have "No Gold Carried Over". Thus, do not be shy to get your gold reserves to the negatives.
* Read the [[How to play Drakes|How-To-Play Drakes]] page if you are not familiar with how Drakes are played.

== Scenario 1: The Hunt ==

This is a large map scenario where you start with a set amount of drake units. Burners and Gliders. You can see 2 villages on the map. Try to capture them. They have 1 Drake Warrior and 1 Drake Fighter in them. You have to kill a specific amount of units to win. There are several AI sides, each fighting the other. If you position your drakes carefully, you can get to a farming spot where you can +16 XP per kill (level 2 enemy) units. This is located at the eastern shore of the island. The counter counts for any unit your side kills so try not to kill only level 1 units as you are denying the XP farm you deserve.

== Scenario 2: Reclamation ==

This is the scenario where your drakes will be fighting orcs. You start near the southwestern shore with a few spawned units and Reshan. There is an enemy leader nearest to you. Your first task: annihilate that orc and prevent him from recruiting any units after the first turn. Orcs will also recruit "boat" units. These have 0% defense on villages so lure them their and instantly kill them with drakes. One of the southern villages has a Clasher unit. On first dawn, Karron will arrive with his Flight of Drakes. They will be targeting side 3. There is a lore book at the north of the island. You win by accomplishing two things: encircling the enemy orc leader (the orange one) with your drakes and destroying all boat units. Karron's flight will not follow your instructions and try to kill all the orcs so you have to capture the orcish leader first.

For your benefit, it is recommended to try levelling Gorlack here to level 3 or very near it. Same goes for Reshan.

== Scenario 2X: Victory Feast ==
Cutscene Only Scenario.
== Scenario 3: The Contention ==

Reshan is your only recalled unit in this scenario. You have to defeat Karron or resist until the end of turns. Your recruit list will be subjected to the '''Ways of Morogor'''. To explain it..you can recruit one unit type at a time and then it will reset. You will also have 2 Intendants from the fighter caste (Drake Warrior) and the clasher caste (Drake Thrasher). Karron will have the same (intendants from each other caste). Karron has a Drake Arbiter unit and this should be taken out as soon as possible. He is a real nuisance. The key to victory is having village ownership of 7+ villages at all times and outlasting Karron's units. Do not worry if you lose units here. They get sent to your recall list. You should focus on getting clashers to take out Karron if you manage to reach him.

If you succeed in defeating Karron, you will get an item '''Dragon Claws''' which will give Gorlack a superior melee damage boost.

== Scenario 3X: Final Departure ==

Cutscene Only Scenario.

== Scenario 4: Journey ==
You start with your keep on the southwestern isle. There are enemy merfolk leaders north and east of your location. There are enemy naga as well on the northeastern isle. However, if Reshan can get near the naga leader, they will become your allies. Reshan can do this effortlessly if he is a level 2 Sky Drake or higher. Using Fire Drakes and Drake Warriors here is recommended. Additionally, if you have Sky Drakes, you can recall them as well. Sky Drake receives a constant 50% defense on this map and is not hindered by deep water. It is imperative to get a good mix of Fire Drakes, Drake Warriors and Sky Drakes in this scenario.

On set intervals (night time), the merfolk leader (the purple one) will summon a Kraken and the naga leader will summon sea serpents. Krakens are menacing to battle and should be lured out of deep water. Try to kill as many Krakens as possible while retaining 100% village ownership. Krakens provide +24 XP to the unit which killed it so take this as an opportunity to get experience drakes (Blademasters, Flamehearts, Inferno and Hurricane Drakes).

The side 2 Merfolk leader is a bit bold. Try to take him out as soon as the scenario starts to make it easier.

Clashers are not available for this scenario (story reasons).

== Scenario 5: Threshold ==

You start of the southwestern edge of the Three Sisters island with some spawned units. There is a loyalist enemy side and several monster sides and an allied saurian side. Try to eradicate that lieutenant on the castle by turn 1 or turn 2. When he dies, the saurians flip over to your side. '''Recruiting and recalling units have been disabled in this scenario.''' There are three temples north of your starting location. Moving units onto them will give you free units (2 saurian augurs, 1 skirmisher, 1 swamp lizard and 1 water serpent and 2 rats). There is no gold carryover and monster spawns are infinite. Try to use this scenario as a means to farm XP for your current set of units. This scenario offers a very good opportunity to get Gorlack to level 4. You win this scenario by capturing all villages so try to delay that and focus on farming some XP.

There is also a lore book at the northern reef of the map.

== Scenario 5X: Early Arrival ==
Cutscene Only Scenario.
== Scenario 6: Landfall ==

In this scenario you have to annihilate all enemy units. Your enemies are the Loyalists. You have access to Clasher recruitment and the clasher caste recalls have been restored to you. There is a beacon right next to your keep/encampment. Lighting it will cause your allies, Karron, his drake flight and the saurians to spawn. Karron's flight will spawn to the west of the human fort and saurians will attack from the north. You have been given the opportunity to time when you wish to light the beacon. Turn 4 is a safe bet to light it. Turn 5 is probably more optimal.

Your enemy will be recruiting an assortment of Loyalist units. The units to watch out for are Longbowmen, Pikemen, Knights and Lancers. These have the most potential of taking out your drakes (and saurians). There are mountains north of your keep. Recruit/recall Drake Clashers/Drake Arbiters and position them on mountains, backed by Fire Drakes and a Soothsayer. Try to lure the human army away from their fort and then light the beacon. Your allies will mostly decimate the fort so you can only focus on the human attack force that was dispatched to fight you.

If you have not already done so, try to level up a Clasher to an Arbiter (Trust me on this).

== Scenario 6X: Winds of Fate ==
Cutscene Only Scenario.
== Scenario 7: Harvest ==

This is perhaps the most controversial scenario of the whole campaign as the tactic employed here is strange. The elves will welcome you in. Recall your most powerful damage dealers. Take your sweet time positioning the units next to each leader. Attack at morning time. Kill all leaders within a single turn. Deal with the rest later.

* For the Ancient Wose leader, Gorlack (he should be a destructive Armageddon Drake by now) and 2 Inferno/Fire drakes are enough.
* For the Elven marshal, 2 Blademasters, 1 Thrasher and 1 Arbiter.
* For the cat, 2 Drake Warriors and maybe a Sky Drake.
* For the mermaid, 1 Drake Warrior, the saurian heroes and Reshan.

This scenario has a special mechanic. If your drakes attack an enemy on a forest hex, they will ignite the hex and this fire will spread. Use this to your advantage.

When the Elven Lady dies, she will drop an artifact, the '''Sapphire of Ice'''. This will grant any unit with a ranged cold attack (which increments by level). The best unit to equip this is a Drake Warden/Drake Arbiter. Drake Enforcer/Drake Thrasher (but the extra attack just clutters the side bar UI so maybe not). Any other choice is good, but not as good as the Warden using it.

There is a lore book on the location of the cat "Princess Mew". You should really read it.

== Scenario 8: Overlook ==

The drakes have to escape through a cave. There are elves pursuing you (since you well...you know). Recruit some saurians to delay the elves and recall Fire Drakes and Drake Flares to navigate one of the tunnels. There is lore book inside the left tunnel. You will encounter undead inside these caves. Dispatch the Death Knight leader quickly and proceed onwards.

You will encounter an Ancient Lich who can recruit Liches and Spectres. However, if you attack him, you are prompted to form a truce or destroy him. The choice is up to you. However, forming a truce has a better benefit. He will open the escape route and delay the elves.

You have the chance to farm the level 3 elves for XP but it is a bit risky as there are Sylphs which can easily take out drakes and move relatively faster in caves. Retreat through the cave, remembering that Reshan should be the last unit to escape.

== Scenario 9: Ancestor ==

You start on a Keep/Encampment with the Saurian heroine units. You might have enough gold for 9 recalls (might be different by difficulty). The terrain is mostly snowy and swampy. There are monster units battling each other everywhere. Perfect farming spot.

=== Recall Priority: ===
* Hurricane/Sky Drakes: Best recallable option. Snowy Terrain? No problem. They will just fly over most terrain without any movement impediments at all.
* Drake Warriors: You can never go wrong with Drake Warriors.
* Fire Drakes. Two or more.
* Drake Flameheart: Only if you have a bunch of level 2 drakes recalled and can level up.
* One Saurian Soothsayer (to supplement Zedrix in healing). Optional.
* One Saurian Ambusher (she can level up fast here). Optional.

=== Ignore ===
* Drake Clasher caste recalls. It is a shame that the campaign's design does not encourage usage of clashers in most scenarios.
* Saurian Oracles. Most monsters are cold resistant, so might have these units sit this one out.

=== Monster Priority ===
* Yeti: Dangerous to confront without adequate support. 32 XP on kill so should be dealt with if encountered.
* Greater Icemonax: Probably has a masters degree in being the most annoying. resistant to most damage types. Avoid if able since you can get better kills here.
* Dread Bat: One Word. Annoying.
* Gryphon. Has a high chance of spawning next to your keep at start.
* Direwolf: perfect for XP farm.
* Cave Bear: good farm option

Your goal is get Gorlack to the beacon on top of the volcanic mountain range. Once there, you will meet a dragon and his wyrms. Then they will become your allies and finally, you have purge the map of all enemies.

== Scenario 10: Fire Meets Steel ==

You start at a new eerie establish on the volcanic mountain range. '''You can recruit level 2 drakes and saurians'''. At this point, your recruit list is now identical to the '''Age of Heroes''' Era's Drakes faction. Your enemies are dwarves.

In this scenario you have to resist the dwarven offensive for three days (18 turns). Here, recalling 2 Hurricane Drakes is obligatory for the swift victory tactics. Recall your loyal intendants and a Flameheart. Recruit Clashers and Burners, but prioritize on Drake Clasher recruitment. Losing a village deprives of +4 income so you should be focusing on retaining most of the villages.

Dwarven Thunderguards, Stalwarts and Berserkers should be approached with caution as they can gang up on your units. The dwarves also spawn from the mountain tunnels and the leader himself will be sending Gryphon Riders and Gryphon Masters This is where your Hurricane drakes come in. Send them to circumvent the enemy and collapse the tunnels. That way the subsequent waves will have less units to deal with. Keep the dwarves at bay by exploiting the mobility of the drakes and the lava reef.

At the end of the scenario, Reshan is returned to you.

== Scenario 11: Crosswind ==

The final scenario. Your enemy is the remnants of the Flight of Karron. The victory objective is surrounding Karron with 6 of your units. Additionally, the Saurian Flanker heroine (it's a she)...will turn on you. Oh, no! A spoiler! Deal with it.

The key to this scenario is Reshan himself.

Turn 1: Send Reshan south to the villages. When he captures them, he will spawn allies (veteran Nagas and Saurians, and swamp affinity monster units). There is another village near the mountain that does another spawn.
Likewise, recall another Hurricane Drake and send him to the village at the western/left edge of the map. The village spawns 1 troll, a giant spider and an greater icemonax.

Once Reshan has captured the 2 villages, rush all your spawned saurians, and monsters towards Karron. Reshan should be heading to Karron's keep and nullifying any chances of him recruiting. This is a bit tricky but doable.

=== Recall Priority ===
* Drake Blademasters. Probably the best units for this campaigns you can have. Recall all of them. Every single one.
* Drake Warden with Sapphire Orb.
* Saurian Oracles (as many as you got). Recruit if you lost all of them.
* A Drake Flameheart (to supplement the Oracles)
* Saurian Flankers

There are 2 lore tablets/secrets here (northeast and southeast of the starting keep).

Karron will spawn his Burner caste veterans and Glider caste veterans when he is attacked. Keep this in mind.

Once Reshan occupies the keep, Karron will not go for the keep, instead he will move to attacking to whatever he sees. This is a good moment to get him surrounded as your skirmishing flankers and swamp lizards are already there with nagas.

For the honorable way, just let Karron walk to his keep, while occupying the 5 adjacent hexes of the keep so when he moves, he will recruit just 1 unit and then on your turn, kill that unit and place your unit to capture him.

== Scenario 12: Epilogue ==
Cutscene Only Scenario.

[[Category: Campaigns - Walkthroughs]]
[[Category: Campaigns - Winds of Fate]]

Winds of Fate

2022-01-20T04:10:27Z

Name: