WML Abilities
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 [event]s must be added to the game explicitly, in addition to the unit with the ability / weapon special!
How to include [event]s?
- Add it directly to the scenario file.
- Add it directly to the [era].
- Add it inside a [unit_type] definition.
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 load_resource.
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=_ "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
And insert this event to your [scenario], [multiplayer], [unit_type] or [era]:
[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_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 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}
#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
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)}
#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
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:
#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]
#enddefIt 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 (https://r.wesnoth.org/t20100).
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=_ "This unit gains an additional point added to its melee damage whenever it kills a living unit."
[/dummy]
[/abilities]
[event]
name=die
first_time_only=no
[filter]
[not]
status=not_living
[/not]
[/filter]
[filter_second]
ability=soultaker
[/filter_second]
[unstore_unit]
variable=second_unit
{COLOR_HEAL}
text= _ "+1 damage"
[/unstore_unit]
[object]
silent=yes
duration=forever
[filter]
x,y=$x2,$y2
[/filter]
[effect]
apply_to=attack
range=melee
increase_damage=1
[/effect]
[/object]
[/event]
[+abilities]
#enddefAnd the following in the unit's [abilities] tag:
{ABILITY_SOULTAKER}
Soultaker (weapon special)
Unit with this weapon special will gain an additional point of damage per strike for that weapon every time it kills an enemy with this attack. Coder Ravana, made for ageless era (https://r.wesnoth.org/t25274) based on previous ability.
To give a unit the weapon special, load the following code:
#define WEAPON_SPECIAL_SOULTAKER
[dummy]
id=soultaker
name= _ "soultaker"
description=_"This unit gains an additional point added to its damage whenever it kills a living unit."
[/dummy]
[/specials]
[/attack]
[event]
name=die
first_time_only=no
id=soultaker_event
[filter]
[not]
status=not_living
[/not]
[/filter]
[filter_second_attack]
special_id=soultaker
[/filter_second_attack]
[unstore_unit]
variable=second_unit
{COLOR_HEAL}
text= _ "+1 damage"
[/unstore_unit]
[object]
silent=yes
duration=forever
[filter]
x,y=$x2,$y2
[/filter]
[effect]
apply_to=attack
name=$second_weapon.name
increase_damage=1
[/effect]
[/object]
[/event]
[+attack]
[+specials]
#enddefAnd the following in the attack's [specials] tag:
{WEAPON_SPECIAL_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, made for Melon's Youkai faction (https://r.wesnoth.org/t22539)
#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"
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]
[/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_id=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_id=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_id=weapon_charm
[/filter_attack]
[filter_second]
canrecruit=no
level=0,1
[not]
status=not_living
[/not]
[/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
boolean_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,charmed}
[/event]
[+attack]
[+specials]
#enddefWorks
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
[works]
id=peasant_works
name="works"
description= _ "This unit produces 1 gold per turn."
[/works]
#enddef
Put this event into your code.
[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]
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."
active_on=offense
[/mindflay]
#enddef
Include these events into your scenario:
[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 add -$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]
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 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 his own turn.
#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
#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
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.
#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
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:
[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]
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:
[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]
This is the event:
[event]
name=attacker_hits
first_time_only=no
[filter_attack]
special_id=whirlwind
[/filter_attack]
{VARIABLE has_drain 0} # Notifies the weapon specials
{VARIABLE has_slow no}
{VARIABLE has_poison no}
{FOREACH weapon.specials.damage i}
[if]
[variable]
name=weapon.specials.drains.id
equals=drains
[/variable]
[then]
{VARIABLE has_drain 1}
[/then]
[/if]
{NEXT i}
[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
equals=0
[/variable]
[else]
[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=1 #If you want to use it in an era, use side=$unit.side instead
[/not]
[not] #The target unit is already hit by the attack
x,y=$x2,$y2
[/not]
[not] #Undead are undrainable
race=undead
[/not]
[/filter]
variable=units
[/store_unit]
{VARIABLE healed_amount 0}
{FOREACH units i}
[switch] #Check the resistances
variable=weapon.type
[case]
value=arcane
{VARIABLE_OP healed_amount add "$($units[$i].resistance.arcane*$weapon.damage)"}
[/case]
[case]
value=fire
{VARIABLE_OP healed_amount add "$($units[$i].resistance.fire*$weapon.damage)"}
[/case]
[case]
value=cold
{VARIABLE_OP healed_amount add "$($units[$i].resistance.cold*$weapon.damage)"}
[/case]
[case]
value=blade
{VARIABLE_OP healed_amount add "$($units[$i].resistance.blade*$weapon.damage)"}
[/case]
[case]
value=pierce
{VARIABLE_OP healed_amount add "$($units[$i].resistance.pierce*$weapon.damage)"}
[/case]
[case]
value=impact
{VARIABLE_OP healed_amount add "$($units[$i].resistance.impact*$weapon.damage)"}
[/case]
[/switch]
{NEXT i}
[store_unit] #Float the healed amount over the unit, like if it had drained
[filter] #Two numbers will float, the one from the regular hit and one from this
x,y=$x1,$y1
[/filter]
variable=FLOATING_TEXT_temp
[/store_unit]
[unstore_unit]
variable=FLOATING_TEXT_temp
red,green,blue=0,255,0
text=$($healed_amount/200) #Operating with huge numbers because rounding is a problem
[/unstore_unit]
{CLEAR_VARIABLE FLOATING_TEXT_temp}
[heal_unit]
[filter]
x,y=$x1,&y1
[/filter]
amount=$($healed_amount/200)
animate=no
[/heal_unit]
{CLEAR_VARIABLE units,healed_amount}
[/else]
[/if]
[harm_unit]
[filter]
[filter_adjacent]
x,y=$x1,$y1
[/filter_adjacent]
[not]
side=1 #If you want to use it in an era, use side=$unit.side instead
[/not]
[not] #If you want to use it in an era, use side=$unit.side instead
x,y=$x2,$y2
[/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]