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;

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; currently there is no way of removing a modification.

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 LuaWML/Units#wesnoth.effects.

[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_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 coma-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
  • 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
  • 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.
• 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.
• 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.
• loyal: no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
• 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).
  • [movement_costs]: a subtag that describes the new movement costs just like in UnitsWML
• 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).
  • [vision_costs]: a subtag that describes the new vision costs just like in UnitsWML
• 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).
  • [jamming_costs]: a subtag that describes the new jamming costs just like in UnitsWML
• 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.
  • [defense]: a subtag that describes the new defense just like in UnitsWML
• 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.
  • [resistance]: a subtag that describes the new resistance just like in UnitsWML
• variation: switches the unit into one of its variations. Similar to the type effect below, this might not behave properly outside of [advancement], and cannot be combined with type in the same object due to a bug.
  • 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.
• 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.
• image_mod: modify the image path function (ImagePathFunctions) of all the unit's frames.
  • 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 to use. Can be set to "none" to disable the ellipse.
• 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

Movement and Vision

Wesnoth 1.14 introduced vision points, which default to a reserved value (-1) which means "the same as the max movement points". Using an effect with apply_to=vision sets the number of vision points, and from then on they're no longer affected by the movement points.

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.
• 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.

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]

See Also

• UnitTypeWML
• ReferenceWML
• AnimationWML