WML Abilities
From The Battle for Wesnoth Wiki
Remember that you must include the WML ability code in every scenario where you intend them to work. Or include them in the unit file inside the [unit_type] tag.
Some abilities require macros from Utilities.
Contents
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:
#define WEAPON_SPECIAL_KNOCKBACK
[dummy]
id=knockback
name= _ "knockback"
female_name= _ "female^knockback"
description=_ "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."
[/dummy]
#enddef
And insert this event to your [scenario], [multiplayer], [unit_type] or [era]:
[event]
name=attacker hits
first_time_only=no
[filter_attack]
special=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]
[then]
[if]
[have_unit]
x,y=$x1,$y1
[filter_adjacent]
x,y=$x2,$y2
adjacent=n
[/filter_adjacent]
[/have_unit]
[then]
{VARIABLE knockback_direction n}
[/then]
[else]
[if]
[have_unit]
x,y=$x1,$y1
[filter_adjacent]
x,y=$x2,$y2
adjacent=ne
[/filter_adjacent]
[/have_unit]
[then]
{VARIABLE knockback_direction ne}
[/then]
[else]
[if]
[have_unit]
x,y=$x1,$y1
[filter_adjacent]
x,y=$x2,$y2
adjacent=se
[/filter_adjacent]
[/have_unit]
[then]
{VARIABLE knockback_direction se}
[/then]
[else]
[if]
[have_unit]
x,y=$x1,$y1
[filter_adjacent]
x,y=$x2,$y2
adjacent=s
[/filter_adjacent]
[/have_unit]
[then]
{VARIABLE knockback_direction s}
[/then]
[else]
[if]
[have_unit]
x,y=$x1,$y1
[filter_adjacent]
x,y=$x2,$y2
adjacent=sw
[/filter_adjacent]
[/have_unit]
[then]
{VARIABLE knockback_direction sw}
[/then]
[else]
[if]
[have_unit]
x,y=$x1,$y1
[filter_adjacent]
x,y=$x2,$y2
adjacent=nw
[/filter_adjacent]
[/have_unit]
[then]
{VARIABLE knockback_direction nw}
[/then]
[/if]
[/else]
[/if]
[/else]
[/if]
[/else]
[/if]
[/else]
[/if]
[/else]
[/if]
[store_locations]
[not]
[filter]
[/filter]
[/not]
[filter_adjacent_location]
x,y=$x2,$y2
adjacent=-$knockback_direction
[/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_direction,knockback_target_hex}
[/then]
[/if]
[/event]
Charm
When a unit is hit with a charm attack, it instantly jumps to the attacker's side, and returns to it's original side at the beginning of that side's 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}
#define CHARM FILTER WEAPON
[event]
name=attacker_hits
first_time_only=no
[filter]
{FILTER}
[/filter]
[special_filter]
weapon={WEAPON}
[/special_filter]
{STORE_UNIT_VAR x,y=$x1,$y1 side charmer_side}
{STORE_UNIT_VAR x,y=$x2,$y2 side charmed_side}
{IF_VAR charmer_side not_equals $charmed_side (
[then]
{MODIFY_UNIT x,y=$x2,$y2 variables.real_side $charmed_side}
{MODIFY_UNIT x,y=$x2,$y2 side $charmer_side}
{MODIFY_UNIT x,y=$x2,$y2 moves 1}
{MODIFY_UNIT x,y=$x2,$y2 attacks_left 1}
{VARIABLE_OP varname format "side_$charmed_side|_units_charmed"}
{VARIABLE $varname yes}
{CLEAR_VARIABLE varname}
[/then]
)}
{CLEAR_VARIABLE charmer_side}
{CLEAR_VARIABLE charmed_side}
[/event]
[event]
name=side turn
first_time_only=no
{VARIABLE_OP this_side_charmed to_variable "side_$side_number|_units_charmed"}
{IF_VAR this_side_charmed equals yes (
[then]
[store_unit]
[filter]
[not]
side=$side_number
[/not]
[/filter]
variable=possibly_charmed
kill=no
[/store_unit]
{FOREACH possibly_charmed i}
{VARIABLE_OP real_side format "0$possibly_charmed[$i].variables.real_side"}
{IF_VAR real_side not_equals "0" (
[then]
{IF_VAR side_number equals $possibly_charmed[$i].variables.real_side (
[then]
{CLEAR_VARIABLE possibly_charmed[$i].variables.real_side}
{VARIABLE possibly_charmed[$i].side $side_number}
[unstore_unit]
variable=possibly_charmed[$i]
find_vacant=no
[/unstore_unit]
[/then]
)}
[/then]
)}
{NEXT i}
{CLEAR_VARIABLE possibly_charmed}
[/then]
)}
[/event]
#enddef
Bloodlust
Bloodlust is a very simple ability. If a unit that has 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)}
#define BLOODLUST FILTER
[event]
name=die
first_time_only=no
[filter_second]
{FILTER}
[/filter_second]
{MODIFY_UNIT x,y=$x2,$y2 moves 0}
{MODIFY_UNIT x,y=$x2,$y2 attacks_left 1}
[/event]
#enddef
Pickpocket
This special could also be called loot. When a unit with this attack special sucessfully hits an enemy unit, it gains a certain amount of gold.
To do this, use this code:
#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"
name_inactive= _ "pickpocket"
description= _ "pickpocket :
Gain money for attacking your foe. Each strike scores you one gold."
description_inactive= _ "pickpocket :
Gain money for attacking your foe. Each strike scores you one gold."
apply_to=opponent
[/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=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=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
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}
{CLEAR_VARIABLE pickpocketed}
[/event]
[+attack]
[+specials]
#enddef
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
to
[event]
name=attack_end
first_time_only=no
Soultaker
Any unit with this ability will gain an additional point of damage per strike every time it kills an enemy. Coder(s) unknown, made for Melon's Youkai faction (http://www.wesnoth.org/forum/viewtopic.php?f=19&t=20100).
To give a unit the ability, place the following in any .cfg file loaded by the campaign or era:
#define ABILITY_SOULTAKER
[dummy]
id=soultaker
name= _ "soultaker"
description=_ "Soultaker:
This unit gains an additional point added to its maximum damage whenever it kills a living unit."
[/dummy]
[/abilities]
[event]
name=die
first_time_only=no
[filter]
[not]
[wml_filter]
[status]
not_living="yes"
[/status]
[/wml_filter]
[/not]
[/filter]
[filter_second]
ability=soultaker
[/filter_second]
[unstore_unit]
variable=second_unit
{COLOR_HEAL}
text= _ "+1 damage"
find_vacant=no
[/unstore_unit]
[object]
silent=yes
duration=forever
[filter]
x,y=$x2,$y2
[/filter]
[effect]
apply_to=attack
range=melee
increase_damage=1
increase=1
[/effect]
[/object]
[/event]
[+abilities]
#enddef
And the following in the unit's [abilities] tag:
{ABILITY_SOULTAKER}
Charm (Type 2)
An attack special. If the attack hits, and the target is level 0 or 1, the target is converted to the attacker's side. However, if it misses, the attacker is converted to the defender's side. Maintainer is krotop, using 1.6.x syntax (and compatible with 1.7.x], made for Melon's Youkai faction (http://www.wesnoth.org/forum/viewtopic.php?f=21&t=22539)
#define WEAPON_SPECIAL_CHARM
# Canned definition of the Charm 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_charm
name= _ "charm"
name_inactive= _ "charm"
description= _ "Charm :
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 ennemy leader or a non-living creature."
description_inactive= _ "Charm :
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 ennemy leader or a non-living creature."
apply_to=opponent
[/dummy]
[/specials]
[/attack]
# event that creates a variable at the beginning of the fight to check if the attacker hit at least once by the end.
[event]
name=attack
first_time_only=no
[filter_attack]
special=weapon_charm
[/filter_attack]
[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=unit_att_with_charm
mode=append
[/store_unit]
[set_variable]
name=unit_att_with_charm.variables.charm_has_worked
value=no
[/set_variable]
[unstore_unit]
variable=unit_att_with_charm
[/unstore_unit]
{CLEAR_VARIABLE unit_att_with_charm}
[/event]
# 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
[filter_attack]
special=weapon_charm
[/filter_attack]
[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=unit_att_with_charm
mode=append
[/store_unit]
[set_variable]
name=unit_att_with_charm.variables.charm_has_worked
value=yes
[/set_variable]
[unstore_unit]
variable=unit_att_with_charm
[/unstore_unit]
{CLEAR_VARIABLE unit_att_with_charm}
[/event]
# event that shifts a unit to the other side
# if the defending unit
# - was not lvl1 or lvl0
# - and was not a recruiting unit
# - and was a not a "non-living" creature
# then :
# -> if the attacker missed all attacks, it goes to the defender side.
# -> if the attacker hit once at least, the defender goes to the attacker side.
[event]
name=attack_end
first_time_only=no
[filter_attack]
special=weapon_charm
[/filter_attack]
[filter_second]
canrecruit=no
[and]
level=0
[or]
level=1
[/or]
[/and]
[and]
[not]
[filter_wml]
[status]
not_living=yes
[/status]
[/filter_wml]
[/not]
[/and]
[/filter_second]
[store_unit]
[filter]
x,y=$x1,$y1
[/filter]
variable=charmer
mode=append
[/store_unit]
[store_unit]
[filter]
x,y=$x2,$y2
[/filter]
variable=charmed
mode=append
[/store_unit]
[if]
[variable]
name=charmer.variables.charm_has_worked
equals=no
[/variable]
[then]
[set_variable]
name=charmer.side
value=$charmed.side
[/set_variable]
[unstore_unit]
variable=charmer
text="Charm failed!"
{COLOR_HARM}
[/unstore_unit]
[/then]
[else]
[set_variable]
name=charmed.side
value=$charmer.side
[/set_variable]
[unstore_unit]
variable=charmed
text="Charmed!"
{COLOR_HEAL}
[/unstore_unit]
[/else]
[/if]
{CLEAR_VARIABLE charmer}
{CLEAR_VARIABLE charmed}
[/event]
[+attack]
[+specials]
#enddef
Works
Unit with ability works will produce 1 gold per turn.
Put this macro into you code before the last piece of code.
#define ABILITY_WORKS
[leadership]
value=0
id=peasant_works
cumulative=no
name="works"
description= _ "Works:
This unit produces 1 gold per turn."
[/leadership]
#enddef
Put this event into your code.
[event]
name=side turn
first_time_only=no
[store_unit]
[filter]
#your filter here... for example type=Peasant
[/filter]
variable=worker
kill=no
[/store_unit]
{FOREACH worker i}
[gold]
side=$side_number
amount=1
[/gold]
[unstore_unit]
variable=worker[$i]
text="1"
red,green,blue=255,255,0
[/unstore_unit]
{NEXT i}
{CLEAR_VARIABLE worker}
[/event]
And give the unit the ability like this
[object]
silent=yes
[effect]
apply_to=new_ability
[abilities]
{ABILITY_WORKS}
[/abilities]
[/effect]
[/object]
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.
#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."
[/mindflay]
#enddef
Include these events into your scenario.
[event]
name=attack
first_time_only=no
[special_filter]
weapon=mind flay
[/special_filter]
{VARIABLE hit_number 0}
[/event]
[event]
name=attacker_hits
first_time_only=no
[special_filter]
weapon=mind flay
[/special_filter]
{VARIABLE_OP hit_number add 1}
[/event]
[event]
name=attack_end
first_time_only=no
[special_filter]
weapon=mind flay
[/special_filter]
{VARIABLE_OP second_unit.experience add -$hit_number}
{VARIABLE_OP unit.experience add $hit_number}
[unstore_unit]
variable=unit
find_vacant=no
text=$hit_number
blue=255
[/unstore_unit]
[unstore_unit]
variable=second_unit
find_vacant=no
[/unstore_unit]
{CLEAR_VARIABLE hit_number}
[/event]
Note: In dev version substitute "name=" instead of "weapon=".
Initiative
Initiative is an aura ability. Much like Leadership, it effects adjacent allies but not the unit itself.
#define AURA_INITIATIVE TYPE
[dummy]
id=initiative
name= _ "initiative"
description= _ "Initiative:
Adjacent allies are granted Firststrike with all weapons."
[/dummy]
[/abilities]
[event]
name=attack
first_time_only=no
[filter]
[filter_adjacent]
type={TYPE}
is_enemy=no
[/filter_adjacent]
[/filter]
{FOREACH unit.attack i}
{VARIABLE unit.attack[$i].specials.firststrike.id "firststrike"}
{NEXT i}
[unstore_unit]
variable=unit
[/unstore_unit]
[/event]
[event]
name=attack
first_time_only=no
[filter_second]
[filter_adjacent]
type={TYPE}
is_enemy=no
[/filter_adjacent]
[/filter_second]
{FOREACH second_unit.attack i}
{VARIABLE second_unit.attack[$i].specials.firststrike.id "firststrike"}
{NEXT i}
[unstore_unit]
variable=second_unit
[/unstore_unit]
[/event]
[event]
name=attack_end
first_time_only=no
[filter]
[wml_filter]
[attack]
[specials]
[firststrike]
id=firststrike
[/firststrike]
[/specials]
[/attack]
[/wml_filter]
[/filter]
{FOREACH unit.attack i}
{CLEAR_VARIABLE unit.attack[$i].specials.firststrike}
{NEXT i}
[unstore_unit]
variable=unit
[/unstore_unit]
[/event]
[event]
name=attack_end
first_time_only=no
[filter_second]
[wml_filter]
[attack]
[specials]
[firststrike]
id=firststrike
[/firststrike]
[/specials]
[/attack]
[/wml_filter]
[/filter_second]
{FOREACH second_unit.attack i}
{CLEAR_VARIABLE second_unit.attack[$i].specials.firststrike}
{NEXT i}
[unstore_unit]
variable=second_unit
[/unstore_unit]
[/event]
[+abilities]
#enddef
A WML filter may be added instead of the type if you want some units of that type to not have the ability.
Blitz
Blitz is an aura ability. Much like Leadership, it effects adjacent allies but not the unit itself.
#define AURA_BLITZ TYPE
[dummy]
id=blitz
name= _ "blitz"
description= _ "Blitz:
Allies that start their turn adjacent to this unit are granted Skirmisher for that turn."
[/dummy]
[/abilities]
[event]
name=side turn
first_time_only=no
[store_unit]
[filter]
[wml_filter]
blitzed=1
[/wml_filter]
[/filter]
variable=blitz_refresh
[/store_unit]
{FOREACH blitz_refresh i}
{CLEAR_VARIABLE blitz_refresh[$i].abilities.skirmisher}
{VARIABLE blitz_refresh[$i].blitzed 0}
[unstore_unit]
variable=blitz_refresh[$i]
[/unstore_unit]
{NEXT i}
[store_unit]
[filter]
side=$side_number
[filter_adjacent]
type={TYPE}
is_enemy=no
[/filter_adjacent]
[/filter]
variable=blitzed
[/store_unit]
{FOREACH blitzed i}
[if]
[variable]
name=blitzed[$i].abilities.skirmisher.id
not_equals="skirmisher"
[/variable]
[then]
{VARIABLE blitzed[$i].blitzed 1}
{VARIABLE blitzed[$i].abilities.skirmisher.id skirmisher}
{VARIABLE blitzed[$i].abilities.skirmisher.name "skirmisher"}
{VARIABLE blitzed[$i].abilities.skirmisher.description "Skirmisher:
This unit is skilled in moving past enemies quickly, and ignores all enemy Zones of Control."}
[unstore_unit]
variable=blitzed[$i]
[/unstore_unit]
[/then]
[/if]
{NEXT i}
[/event]
[+abilities]
#enddef
A WML filter may be added instead of the type if you want some units of that type to not have the ability.