EffectWML

[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;

[effect]

The tag [effect] is used to describe one modification to a unit. Any number of [effect] tags can be used to describe a complete modification.

Modifications are permanent changes to a unit; however using an [object] with a limited duration to apply an [effect] will cause the unit to be rebuilt without the effect's effects when the duration expires.

The following keys and subtags are always recognized:

• [filter]: only apply this effect if the affected unit matches. See StandardUnitFilter for details.
• times: describes how many times the effect is applied. The default is to apply the effect once. Other possible value : "per level" which means that the effect is applied level times, where level is the unit level. (Version 1.13.5 and later only) Integers are now supported for times.
• apply_to: describes what the effect actually affects. New effect types can be added with LuaAPI/wesnoth#wesnoth.effects. Some examples can be seen in World Conquest.

[effect] uses different keys depending on the value of apply_to. apply_to can take the following values:

• new_attack: will use all other keys and tags as the description of an attack that will be added to the unit. See [attack] in UnitTypeWML.
• remove_attacks: remove the matching attacks. All tags from the attack filter construct will be used to match the attack; see FilterWML. Do not use a [filter] tag otherwise it will not work properly.
• attack: find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see FilterWML. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
  • set_name: change the attack's name (ie identifier).
  • set_description: change the attack's description (ie displayed name).
  • set_type: change the attack type. The standard values are blade, pierce, impact, fire, cold, and arcane.
  • set_range: change the attack range. The standard values are ranged and melee.
  • set_icon: change the attack's icon.
  • [set_specials]: change the attack's specials. The specials to add are given exactly as in the [specials] tag.
    • mode: if append, adds the given specials to the attack. If replace, replaces the existing specials with the given ones. Default replace.
      • (Version 1.15.3 and later only) A deprecation warning is triggered unless the mode attribute is set, although the effect will still be replace. This is to allow the default to change in the 1.17.x series.
  • remove_specials: remove the listed specials. The value of this key is the comma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
  • increase_damage: increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent('%'), the change in damage will be a percentage ratio of the attack's original damage.
  • increase_attacks: increases the number of attack strikes. Like increase_damage, it can be positive or negative, or a percentage.
  • increase_accuracy: increases the attack accuracy; can be positive or negative, or a percentage
  • increase_parry: increases the attack parry bonus; can be positive or negative, or a percentage
  • increase_movement_used: (Version 1.13.2 and later only) increases the movement points used by the attack; can be positive or negative, or a percentage
  • increase_attacks_used: (Version 1.17.13 and later only) increases the attack points used by the attack; can be positive or negative, or a percentage
  • set_damage (Version 1.13.2 and later only) like increase_damage, but sets the damage to a specific value instead of setting it relative to its original value
  • set_attacks (Version 1.13.2 and later only) like increase_attacks, but sets the attacks to a specific value instead of setting it relative to its original value
  • set_accuracy (Version 1.13.2 and later only) like increase_accuracy, but sets the accuracy to a specific value instead of setting it relative to its original value
  • set_parry (Version 1.13.2 and later only) like increase_parry, but sets the parry to a specific value instead of setting it relative to its original value
  • set_movement_used (Version 1.13.2 and later only) like increase_movement_used, but sets the movement used to a specific value instead of setting it relative to its original value
  • set_attacks_used (Version 1.17.13 and later only) like increase_attacks_used, but sets the attacks used to a specific value instead of setting it relative to its original value
  • attack_weight: change the attack's attack_weight. See [attack] in UnitTypeWML for explanations about attack_weight.
  • defense_weight: change the attack's defense_weight. See [attack] in UnitTypeWML for explanations about defense_weight.
  • set_min_range (Version 1.19.4 and later only) modify required distance between units in order to allow using attack
  • set_max_range (Version 1.19.4 and later only) modify required distance between units in order to allow using attack
  • increase_min_range (Version 1.19.4 and later only) modify required distance between units in order to allow using attack
  • increase_max_range (Version 1.19.4 and later only) modify required distance between units in order to allow using attack
• max_attacks: (Version 1.13.2 and later only) change the unit's maximum attacks per turn
  • increase: how much to increase by; can be positive or negative, or a percentage
• hitpoints: modifies the unit's HP and/or max HP.
  • increase: the amount to increase the unit's HP.
  • heal_full: if present and not set to "no" the unit will be put back to full HP.
  • increase_total: will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
  • violate_maximum: it the unit ends up with more than its max HP after these modifications, and this key is present (set to any non-null value, ex. yes), the unit's HP won't be lowered to its max HP.
• movement: modifies the unit's movement points.
  • increase: maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
  • set: maximum movement is set to a specific value.
  • apply_to_vision: (Version 1.15.13 and later only) if set to yes (which is the default), then the vision points will change by the same amount. See Movement and Vision.
• vision: (Version 1.13.2 and later only) modifies the unit's vision points. Note: this has side effects described in Movement and Vision.
  • increase: maximum vision is increased by this amount. It can be positive, negative, or specified as a percentage.
  • set: maximum vision is set to a specific value.
• jamming: (Version 1.13.2 and later only) modifies the unit's jamming points.
  • increase: maximum jamming is increased by this amount. It can be positive, negative, or specified as a percentage.
  • set: maximum jamming is set to a specific value.
• experience: affects the unit's current XP.
  • increase: current XP is increased by this amount. It can be positive, negative, or specified as a percentage.
  • set: current XP is set to a specific value.
• max_experience: affects the amount of XP the unit needs for the next level.
  • increase: how to change the xp; again it can be negative, positive or a percentage.
  • set: current max XP is set to a specific value.
• loyal: no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
• fearless: Add/Remove fearless attribute.
  • set: new value for fearless (boolean). Defaults to yes.
• healthy: Add/Remove healthy attribute.
  • set: new value for healthy (boolean). Defaults to yes.
• movement_costs: speed through specific terrain is modified
  • replace: If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to no.
  • [movement_costs]: a subtag that describes the new movement costs just like under [movetype] if replace is set to "yes" or the addition if "no".
• vision_costs: vision through specific terrain is modified
  • replace: If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to no.
  • [vision_costs]: a subtag that describes the new vision costs just like under [movetype] if replace is set to "yes" or the addition if "no".
• jamming_costs: jamming through specific terrain is modified
  • replace: If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed). Defaults to no.
  • [jamming_costs]: a subtag that describes the new jamming costs just like under [movetype] if replace is set to "yes" or the addition if "no".
• defense: Sets the unit's chance to be hit in specific terrain (100 - the unit's defense as shown in-game).
  • replace: If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. In most cases, adding a positive number makes the unit easier to hit, while adding a negative number makes the unit harder to hit. The new value is added to the absolute value of the old, and the sign of the old value is preserved. Defaults to no.
  • [defense]: a subtag that describes the new defense just like under [movetype] if replace is set to "yes" or the addition if "no".
• resistance: Sets percent damage taken from combat (100 - the unit's resistance as shown in-game)
  • replace: If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. Adding a positive number makes the unit take more damage, while adding a negative number makes the unit take less damage. Defaults to no.
  • [resistance]: a subtag that describes the new resistance just like under [movetype] if replace is set to "yes" or the addition if "no".
• variation: switches the unit into one of its variations. Similar to the type effect below, this might not behave properly outside of [advancement].
  • name: the id of the variation to invoke.
• type: transforms the unit into a new unit_type. This does not work in [trait]; in ActionWML it's recommended to use [transform_unit] instead of an [object] with this effect. This effect cannot be undone with [remove_object].
  • name: the id of the unit_type to invoke.
• status: modifies the status affecting the unit.
  • add: a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [store_unit] and [unstore_unit], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], SingleUnitWML.
  • remove: a list of status modifications to remove.
• zoc: toggle the zone of control.
  • value: new value for zoc (boolean).
• profile: customize the profile of the unit. See UnitTypeWML.
  • portrait: new image to display when the unit speaks.
  • small_portrait: new image to display in unit reports.
  • description: sets the text to display when hovering over the unit's type in the righthand pane.
  • [special_note]: (Version 1.15.2 and later only) Adds or removes a special note in the unit's description.
    • remove: A boolean value specifying whether to add or remove a note. Defaults to no.
    • note (translatable): The text of the note you want to add or remove. If removing a note, this must be an exact match, character-for-character, for the note you want to remove, and must also be in the same textdomain.
    • Since the tag name is the same, notes can also be added using the standard special note macros, eg {NOTE_HEALS}.
    • To remove a note, you can simply suffix {NOTE_REMOVE} to the regular note macro, eg {NOTE_HEALS}{NOTE_REMOVE}.
• new_ability: Adds one or more abilities to a unit.
  • [abilities]: A subtag that contains the ability definitions.
• remove_ability: Removes one or more abilities from a unit. Abilities are not reference counted: added, added, removed = gone.
  • [abilities]: A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag. (Version 1.17.17 and later only) This is now deprecated, use [experimental_filter_ability] instead.
  • (Version 1.17.17 and later only) [experimental_filter_ability]: A subtag that contains the ability definitions like type of abilities, id, or other attributes like affect_self or [affect_adjacent] but not generic filter.
• new_animation: contain animations that will be added to the unit, it can contain multiple animation blocks, and a single "id=" line. That Id should be unique for each effect block and is used by the engine to reuse WML parsing, making the loading faster. See AnimationWML for further reference.
• image_mod: modify the image path function (ImagePathFunctions) of all the unit's frames. Due to a bug, the effect is permanent even inside [object]duration=turn
  • replace: replaces the image path function(s) to be used, e.g. "RC(magenta>red)"
  • add: adds an image path function without removing any existing ones.
  • If needed, you can also define new color palettes here.
• ellipse: Change the image used for the unit's ellipse.
  • ellipse : the new image base path to use. Defaults to misc/ellipse. Can be set to none to disable the ellipse. An ellipse consist of a top and bottom part so by default in the simplest case the game will look for image files misc/ellipse-top.png and misc/ellipse-bottom.png. This can get further modified based on if the unit is a leader (can_recruit), does the unit emit a zone of control (ZoC) and/or is the unit selected. For a unit that is a leader, emits no ZoC and is currently selected the used files would then be misc/ellipse-leader-nozoc-selected-top.png and misc/ellipse-leader-nozoc-selected-bottom.png.
• halo: Change the image used for the unit's halo.
  • halo: the new image to use.
• overlay: Change the unit's overlays.
  • add: the specified overlay will be added to the unit's overlays. It can be a comma separated list with multiple overlays. Note: overlays added in this way cannot be removed by [remove_unit_overlay] until the effect's duration is over.
  • replace: all the unit's overlays will be removed and replaced with the specified one. Again, it can be a comma separated list. Note: overlays replaced in this way cannot be modified by [unit_overlay] or [remove_unit_overlay] until the effect's duration is over.
  • remove: (Version 1.15.0 and later only) the specified overlay will be removed from the unit's overlays. It can be a comma separated list with multiple overlays.
  • (Version 1.15.0 and later only) [unit_overlay] and [remove_unit_overlay] are now equivalent to adding a permanent object with this effect, after checking if the unit already has / already doesn't have the overlay (effects with temporary durations will cause false positives / false negatives in this check).
• recall_cost: (Version 1.13.2 and later only) change a unit's recall cost
  • set: set recall cost to a specific value, or a percentage of original value
  • increase: alter recall cost relative to original value; can be positive or negative, or a percentage
• alignment: (Version 1.13.2 and later only) change a unit's alignment
  • set: the new alignment (one of chaotic, lawful, neutral, liminal)
• new_advancement: (Version 1.13.2 and later only) add new advancement choices to the unit
  • replace: whether to replace existing advancement choices; if this key is set to yes, existing advancement choices are cleared only if you're adding a choice of the same type. (That is, unit type advancements are cleared only if you're adding a new unit advancement choice, and AMLA choices are cleared only if you're adding new AMLA choices.)
  • types: a comma-separated list of additional unit types the unit can advance to. (Note: If using this, you probably want to include a filter to prevent the unit from being able to advance to this type once it has already done so.)
  • [advancement]: an advancement choice to add, see AMLAs; you can have several of these tags to add multiple advancement choices at the same time.
• remove_advancement: (Version 1.13.2 and later only) remove existing advancement choices from the unit
  • types: a list of unit type advancements to remove as a possibility
  • amlas: a list of AMLA id attributes; any advancement possibility with the given id will be removed
• level: (Version 1.17.15 and later only) change a unit's level. Note: this key is incompatible with times=per level; if this combination is used, the engine reports a warning and uses times=1 as fallback value
  • set: set level to a specific value; can be positive or negative, but not a percentage
  • increase: alter level relative to original value; can be positive or negative, but not a percentage

Movement and Vision

Wesnoth 1.14 introduced vision points; by default units have the same number of vision points as their max movement points. However, combining effects that change vision with effects that change movement had edge cases which were reworked in 1.16:

Consider a unit with 5 mp, and default vision:

• It has (effectively) 5 mp and 5 vp.
• After (mp + 1), it will have 6 mp and 6 vp.
• After (vp + 2), it will have 5 mp and 7 vp.

In 1.14, using an effect with apply_to=vision breaks the link between vision and movement:

• After (mp + 1) (vp + 2), it will have 6 mp and 8 vp.
• After (vp + 2) (mp + 1), it will have 6 mp and 7 vp.

(Version 1.15.13 and later only), [effect]apply_to=movement has another attribute apply_to_vision, which defaults to true. With that change, the order that the effects are applied in doesn't matter:

• After (mp + 1) (vp + 2), it will have 6 mp and 8 vp.
• After (vp + 2) (mp + 1), it will have 6 mp and 8 vp.

Increasing movement by 50% increases vision by (50% of movement) not by (50% of vision). For a unit that started with 6 mp and 8 vp, the following effect would give it 9 mp and 11 vp.

   [effect]
       apply_to=movement
       increase=50%
   [/effect]

Examples

Effect: apply_to = new_animation

This is the only way to change animations of units after they have been placed on the map. In this example, I add very simple idle animation (taken from Goblin Spearman) to the unit, which moves to hex (x=1, y=5). If you want something more complex, you need to check AnimationWML page.

 [event]
   name = moveto
   [filter]
     x,y = 1,5
   [/filter]
   [object]
     [filter]
       x,y = 1,5
     [/filter]
     [effect]
       apply_to = new_animation
       [idle_anim]
         {STANDARD_IDLE_FILTER}
         start_time=0
         [frame]
           image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
         [/frame]
       [/idle_anim]
     [/effect]
   [/object]
 [/event]

If you are going to use advanced WML and want to add animation to unit, stored in variable, then following example might help you. This way is not efficient if you have no additional logic like inventoriy, shops, advanced unit modifications in your add-on. Is is preferred to use first variant or define all needed animation in unit_type.

 [event]
   name = moveto
   [filter]
     x,y = 1,5
   [/filter]
   [store_unit]
     [filter]
       x,y=1,5
     [/filter]
     variable = stored_unit
   [/store_unit]
   [set_variables]
     name = stored_unit.modifications.object
     [value]
       [effect]
         apply_to = new_animation
         [idle_anim]
           {STANDARD_IDLE_FILTER}
           start_time=0
           [frame]
             image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
           [/frame]
         [/idle_anim]
       [/effect]
     [/value]
   [/set_variables]
   [unstore_unit]
     variable = stored_unit
   [/unstore_unit]
 [/event]

Where to Use Effects

A collection of effects together makes up a "unit modification", which is encased in one of the three types of modification tags: [trait], [object], or [advancement]. Which tag to use depends on the goal of the modification.

• Traits are shown in the unit details on the sidebar. They can be placed in a race or unit type to include the trait in the pool of random traits for that race or unit type, or they can be placed in the global [units] tag to add them to the global pool of random traits. (Note that this can cause out-of-sync errors in multiplayer.)
• Advancements are offered when a unit levels up. If a unit type has both modification advancements and regular advancements, the player can choose either each time they level up.
• Objects are usually placed on the map or added by special events. They also have a built-in facility to automatically remove under certain conditions.

An effect can also be placed in [modify_unit] ActionWML to apply it on-the-fly without keeping a record that it has been applied. This is mainly useful for effects that change transient properties such as current hitpoints or experience. An effect applied in this way is liable to be reverted when the unit is rebuilt in the future, for example when they level up or when an object is removed.

See Also

• UnitTypeWML
• ReferenceWML
• AnimationWML