Difference between revisions of "AbilitiesWML"

From The Battle for Wesnoth Wiki
(Updating the WML reference to 1.2)
Line 2: Line 2:
 
==  Abilities and their effects ==
 
==  Abilities and their effects ==
  
−
There are two types of abilities: ones that apply to units (called ''abilities'') and weapon-based (called
+
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, but by convention only one weapon special should be assigned to any given attack.
−
''specials'').  A unit may have multiple abilities,
 
−
but each attack can only have at most one special.
 
  
−
== Normal abilities ==
+
== The ''[abilities]'' tag ==
−
{| class="gallery" style="text-align:left"
 
−
|-
 
−
! ambush
 
−
| the unit becomes invisible on forest.  Invisible units cannot be seen by enemies and do not possess zone of control, although if an enemy moves next to one, it becomes visible again.
 
−
|-
 
−
! cures
 
−
| unit will heal ''curer_heals_per_turn'' (see [[GameConfigWML]]) hp to all neighbours, up to a total of ''cure_amount''. If a neighbour is poisoned, it will cure the poison instead of healing.
 
−
|-
 
−
! heals
 
−
| unit will heal ''healer_heals_per_turn'' (see [[GameConfigWML]]) hp to all neighbours, up to a total of ''heal_amount''. If a neighbour is poisoned, it will prevent the poison's effect instead of healing.
 
−
|-
 
−
! illuminates
 
−
| all neighbouring hex will be "illuminated", in other words have a different time of day (See [[TimeWML]]). Typically, this will be one step brighter.
 
−
|-
 
−
! leadership
 
−
| the unit will increase the damage of all neighbouring units by +25% per level difference. (If the neighbouring unit is of a higher level, this effect is negated.)
 
−
|-
 
−
! nightstalk
 
−
| the unit becomes invisible during night.
 
−
|-
 
−
! regenerates
 
−
| the unit will heal itself 8 hp per turn. If it is poisoned, it will remove the poison instead of healing.
 
−
|-
 
−
! skirmisher
 
−
| the unit ignores zone of control when moving, but still cannot move directly through an enemy unit
 
−
|-
 
−
! steadfast
 
−
| the unit takes half normal damage when it did not initiate the attack.
 
−
|-
 
−
! teleport
 
−
| the unit can move between any two allied villages for one move point
 
−
|-
 
−
! submerge
 
−
| the unit becomes invisible in deep water.
 
−
|}
 
  
 +
The following tags are used to describe an ability in WML:
  
−
== Attack specials ==
+
* ''[heals]'' modifies the hitpoints of a unit at the beginning the healer's turn
−
{| class="gallery" style="text-align:left"
+
* ''[regenerate]'' modifies the hitpoints of a unit at the beginning of the unit's turn
−
|-
+
* ''[resistance]'' modifies the resistance of a unit to damage
−
! backstab
+
* ''[leadership]'' modifies the damage of a unit
−
| doubles damage whenever there is a unit on the opposite side (location) of the defending unit that distracts it. The distracting unit must be an enemy of the defending unit and not incapacitated (e.g. turned to stone).
+
* ''[skirmisher]'' negates enemy zones of control
−
|-
+
* ''[illuminates]'' modifies the time of day adjacent to the affected units
−
! berserk
+
* ''[teleport]'' allows the unit to teleport
−
| forces the combat to continue until either the attacker or the defender is killed, or until 30 rounds have passed (whichever comes first.)
+
* ''[hides]'' renders the unit invisible to enemies
−
|-
+
 
−
! charge
+
=== Common keys and tags for every ability ===
−
| when attacking, both this weapon and defender get double damage.
+
 
−
|-
+
* ''name'' the name of the ability
−
! drain
+
* ''name_inactive'' the name of the ability when inactive
−
| The controller of this weapon gains health equal to half the damage done (rounded down) whenever this attack hits.
+
* ''description'' the description of the ability
−
|-
+
* ''description_inactive'' the description of the ability when inactive
−
! firststrike
+
* ''affect_self'' if equal to 'yes', the ability will affect the unit that has it
−
| when this weapon is used to defend, the battle proceeds as if it were the attacker (i.e. it attacks first).
+
* ''affect_allies'' if equal to 'yes', the ability will affect allies in the specified adjacent hexes
−
|-
+
* ''affect_enemies'' if equal to 'yes', the ability will affect enemies in the specified adjacent hexes
−
! magical
+
* ''cumulative'' if set to 'yes', this ability will be cumulative with the base value for this ability
−
| this weapon always has a 70% chance of hitting.
+
* ''id'' this ability will not be cumulative with other abilities using this id
−
|-
+
* '''[adjacent_description]''' contains all four of the above keys, which are used when an adjacent unit receives the ability
−
! marksman
+
* '''[filter]''' Standard Unit Filter: If the unit owning the ability does not match this filter, the ability will be inactive
−
| when attacking, this weapon has a minimum of 60% chance of hitting.
+
* '''[filter_adjacent]''' Standard Unit Filter, which takes an extra key ''adjacent'', which is used to specify which adjacent hexes to filter on. ''adjacent'' is a comma seperated list of any combination of these directions: ''n'',''ne'',''se'',''s'',''sw'',''nw''
−
|-
+
* '''[filter_adjacent_location]''' like [filter_adjacent], except that it filters on the locations rather than the units
−
! plague
+
* '''[affect_adjacent]''' each adjacent unit that does not match this filter will not receive its effects
−
| The controller of this weapon is copied onto the tile that any unit this attack killed was on.
+
* '''[filter_self]''' if the owner of the ability does not match this filter, it will not receive the effects of the ability
−
|-
+
* '''[filter_base_value]''' filters on the value before any modifications; uses the keys 'equals', 'not_equals', etc.
−
! poison
+
 
−
| when this weapon hits, the defender becomes poisoned (see [status], [[SingleUnitWML]]).
+
=== Extra keys used by the ''[heals]'' ability ===
−
|-
+
 
−
! slow
+
* ''value'' the amount healed
−
| when this weapon hits, the defender becomes slowed (see [status], [[SingleUnitWML]]).
+
* ''poison'' can be one of ''slowed'',''cured''
−
|-
+
 
−
! stone
+
=== Extra keys used by the ''[regenerate]'' ability ===
−
| when this weapon hits, the defender turns to stone (see [status], [[SingleUnitWML]]).
+
 
−
|}
+
* ''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
 +
* ''add'' adds to resistance
 +
* ''multiply'' multiplies 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
 +
 
 +
=== Extra keys used by the ''[leadership]'' ability ===
 +
 
 +
* ''value'' the percentage bonus to damage
 +
 
 +
=== Extra keys used by the ''[illuminates]'' ability ===
 +
 
 +
* ''value'' the percentage bonus to lawful units
 +
* ''max_value'' the maximum percentage bonus given
 +
 
 +
=== Macros for common abilities ===
 +
 
 +
* ABILITY_AMBUSH
 +
* ABILITY_CURES
 +
* ABILITY_HEALS
 +
* ABILITY_ILLUMINATES
 +
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
 +
* 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:
 +
 
 +
* ''[damage]'' modifies the damage of a weapon
 +
* ''[attacks]'' modifies the number of attacks of a weapon
 +
* ''[chance_to_hit]'' modifies the chance to hit of a weapon
 +
* ''[slow]''
 +
* ''[poison]''
 +
* ''[stones]''
 +
* ''[berserk]''
 +
* ''[firststrike]''
 +
* ''[plague]''
 +
 
 +
=== Common keys and tags for every weapon special ===
 +
 
 +
* ''name'' the name of the special
 +
* ''name_inactive'' the name of the special when inactive
 +
* ''description'' the description of the special
 +
* ''description_inactive'' the description of the special when inactive
 +
* ''active_on'' one of 'defense','offense'; if left out, it uses both
 +
* ''cumulative'' if set to 'yes', this special will be cumulative with the base value
 +
* ''id'' this ability will not be cumulative with other specials using this id
 +
* ''apply_to'' one of 'self','opponent','attacker','defender','both'
 +
* '''[filter_adjacent]''' Standard Unit Filter, which takes an extra key ''adjacent'', which is used to specify which adjacent hexes to filter on. ''adjacent'' is a comma seperated list if any combination of these directions: ''n'',''ne'',''se'',''s'',''sw'',''nw''
 +
* '''[filter_adjacent_location]''' like [filter_adjacent], except that it filters on the locations rather than the units
 +
* '''[filter_self]''' if the owner of the special does not match this filter, it will not receive the effects
 +
* '''[filter_opponent]''' if the opponent does not match this filter, it will not receive the effects of the special
 +
* '''[filter_attacker]''' if the attacker does not match this filter, it will not receive the effects of the special
 +
* '''[filter_defender]''' if the defender does not match this filter, it will not receive the effects of the special
 +
* '''[filter_base_value]''' filters on the value before any modifications; uses the keys 'equals', 'not_equals', ect.
 +
 
 +
=== Macros for common weapon specials ===
 +
 
 +
* 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 ==
 
== See Also ==
  
−
* [[AbilitiesWMLTechnical1.1.3]]
 
 
* [[UnitWML]]
 
* [[UnitWML]]
 
* [[SingleUnitWML]]
 
* [[SingleUnitWML]]
 
* [[ReferenceWML]]
 
* [[ReferenceWML]]

Revision as of 13:10, 3 September 2006

[edit]WML Tags

A:

abilities, about, achievement, achievement_group, add_ai_behavior, advanced_preference, advancefrom, advancement, advances, affect_adjacent, ai, allied_with, allow_end_turn, allow_extra_recruit, allow_recruit, allow_undo, and, animate, animate_unit, animation, aspect, attack (replay, weapon), attack_anim, attacks (special, stats), avoid;

B:

base_unit, background_layer, berserk, binary_path, break, brush;

C:

campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, checkbox, choice, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_palette, color_range, command (action, replay), continue, core, credits_group, criteria;

D:

damage, damage_type, death, deaths, default, defend, defends, defense, delay, deprecated_message, destination, difficulty, disable, disallow_end_turn, disallow_extra_recruit, disallow_recruit, do, do_command, drains, draw_weapon_anim;

E:

editor_group, editor_music, editor_times, effect, else (action, animation), elseif, endlevel, end_turn (action, replay), enemy_of, engine, entry (credits, options), era, event, experimental_filter_ability, experimental_filter_ability_active, experimental_filter_specials, extra_anim;

F:

facet, facing, fake_unit, false, feedback, female, filter (concept, event), filter_adjacent, filter_adjacent_location, filter_attack, filter_attacker, filter_base_value, filter_condition, filter_defender, filter_enemy, filter_location, filter_opponent, filter_own, filter_owner, filter_radius, filter_recall, filter_second, filter_second_attack, filter_self, filter_side, filter_student, filter_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, fonts, for, foreach, found_item, frame;

G:

game_config, get_global_variable, goal, gold, gold_carryover;

H:

harm_unit, has_ally, has_attack, has_unit, has_achievement, have_location, have_unit, heal_on_hit, heal_unit, healed_anim, healing_anim, heals, hide_help, hide_unit, hides;

I:

idle_anim, if (action, animation, intro), illuminates, image (intro, terrain), init_side, insert_tag, inspect, item, item_group;

J:

jamming_costs, join;

K:

kill, killed;

L:

label, language, leader, leader_goal, leadership, leading_anim, levelin_anim, levelout_anim, lift_fog, limit, literal, load_resource, locale, lock_view, lua;

M:

male, menu_item, message, micro_ai, missile_frame, modification, modifications, modify_ai, modify_side, modify_turns, modify_unit, modify_unit_type, move, move_unit, move_unit_fake, move_units_fake, movement_anim, movement costs, movetype, multiplayer, multiplayer_side, music;

N:

not, note;

O:

object, objective, objectives, on_undo, open_help, option, options, or;

P:

part, petrifies, petrify, place_shroud, plague, poison, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, progress_achievement, put_to_recall_list;

R:

race, random_placement, recall (action, replay), recalls, recruit, recruit_anim, recruiting_anim, recruits, redraw, regenerate, remove_event, remove_item, remove_object, remove_shroud, remove_sound_source, remove_time_area, remove_trait, remove_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resolution, resource, return, role, rule;

S:

save, scenario, screen_fade, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_achievement, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, objective, set_menu_item), show_objectives, side, skirmisher, slider, slow, snapshot, sound, sound_source, source (replay, teleport), special_note, specials, split, stage, standing_anim, statistics, status, store_gold, store_items, store_locations, store_map_dimensions, store_reachable_locations, store_relative_direction, store_side, store_starting_location, store_time_of_day, store_turns, store_unit, store_unit_defense, store_unit_defense_on, store_unit_type, store_unit_type_ids, store_villages, story, swarm, sub_achievement, switch, sync_variable;

T:

target, team, teleport (ability, action), teleport_anim, terrain, terrain_defaults, terrain_graphics, terrain_mask, terrain_type, test, test_condition, test_do_attack_by_id, text_input, textdomain, theme, then, tile, time, time_area, topic, toplevel, trait, transform_unit, traveler, true, tunnel;

U:

unhide_unit, unit (action, scenario), unit_overlay, unit_type, unit_worth, units, unlock_view, unpetrify, unstore_unit, unsynced;

V:

value, variable, variables, variant, variation, victory_anim, village, vision_costs, volume;

W:

while, wml_message, wml_schema;

Z:

zoom;

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, but by convention only one weapon special should be assigned to any given attack.

The [abilities] tag

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

  • [heals] modifies the hitpoints of a unit at the beginning 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

Common keys and tags for every ability

  • name the name of the ability
  • name_inactive the name of the ability when inactive
  • description the description of the ability
  • description_inactive the description of the ability when inactive
  • affect_self if equal to 'yes', the ability will affect the unit that has it
  • affect_allies if equal to 'yes', the ability will affect allies in the specified adjacent hexes
  • affect_enemies if equal to 'yes', 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
  • id this ability will not be cumulative with other abilities using this id
  • [adjacent_description] contains all four of the above keys, which are used when an adjacent unit receives the ability
  • [filter] Standard Unit Filter: If the unit owning the ability does not match this filter, the ability will be inactive
  • [filter_adjacent] Standard Unit Filter, which takes an extra key adjacent, which is used to specify which adjacent hexes to filter on. adjacent is a comma seperated list of any combination of these directions: n,ne,se,s,sw,nw
  • [filter_adjacent_location] like [filter_adjacent], except that it filters on the locations rather than the units
  • [affect_adjacent] each adjacent unit that does not match this filter will not receive its effects
  • [filter_self] if the owner of the ability does not match this filter, it will not receive the effects of the ability
  • [filter_base_value] filters on the value before any modifications; uses the keys 'equals', 'not_equals', etc.

Extra keys used by the [heals] ability

  • value the amount healed
  • poison can be one of slowed,cured

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
  • add adds to resistance
  • multiply multiplies 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

Extra keys used by the [leadership] ability

  • value the percentage bonus to damage

Extra keys used by the [illuminates] ability

  • value the percentage bonus to lawful units
  • max_value the maximum percentage bonus given

Macros for common abilities

  • ABILITY_AMBUSH
  • ABILITY_CURES
  • ABILITY_HEALS
  • ABILITY_ILLUMINATES
  • ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
  • 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:

  • [damage] modifies the damage of a weapon
  • [attacks] modifies the number of attacks of a weapon
  • [chance_to_hit] modifies the chance to hit of a weapon
  • [slow]
  • [poison]
  • [stones]
  • [berserk]
  • [firststrike]
  • [plague]

Common keys and tags for every weapon special

  • name the name of the special
  • name_inactive the name of the special when inactive
  • description the description of the special
  • description_inactive the description of the special when inactive
  • active_on one of 'defense','offense'; if left out, it uses both
  • cumulative if set to 'yes', this special will be cumulative with the base value
  • id this ability will not be cumulative with other specials using this id
  • apply_to one of 'self','opponent','attacker','defender','both'
  • [filter_adjacent] Standard Unit Filter, which takes an extra key adjacent, which is used to specify which adjacent hexes to filter on. adjacent is a comma seperated list if any combination of these directions: n,ne,se,s,sw,nw
  • [filter_adjacent_location] like [filter_adjacent], except that it filters on the locations rather than the units
  • [filter_self] if the owner of the special does not match this filter, it will not receive the effects
  • [filter_opponent] if the opponent does not match this filter, it will not receive the effects of the special
  • [filter_attacker] if the attacker does not match this filter, it will not receive the effects of the special
  • [filter_defender] if the defender does not match this filter, it will not receive the effects of the special
  • [filter_base_value] filters on the value before any modifications; uses the keys 'equals', 'not_equals', ect.

Macros for common weapon specials

  • 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

Retrieved from "https://wiki.wesnoth.org/index.php?title=AbilitiesWML&oldid=11582"