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.
• apply_to: describes what the effect actually affects.

[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.
  • 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
  • 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.
• 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.
• 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
• 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.
  • name: the id of the variation to invoke.
• type: transforms the unit into a new unit_type.
  • 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.
• 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 (ImagePathFunctionWML) 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.
• ellipse: Change the image used for the unit's ellipse.
  • ellipse : the new image to use.
• 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.

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