From The Battle for Wesnoth Wiki
Revision as of 20:33, 14 September 2012 by Elvish Hunter (talk | contribs) (Added [effect] apply_to=overlay)

[edit]WML Tags


abilities, about, add_ai_behavior, advance, 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, attack_anim, attacks, avoid;


base_unit, berserk, binary_path, break, brush;


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


damage, 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;


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


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_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, for, foreach, frame, full_heal;


game_config, get_global_variable, goal, gold, gold_carryover;


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


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


jamming_costs, join;


kill, killed;


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


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;


not, note;


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


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


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_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resource, return, role, rule;


save, scenario, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, set_menu_item), show_objectives, side, skirmisher, 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_type, store_unit_type_ids, store_villages, story, swarm, switch, sync_variable;


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


unhide_unit, unit, unit_overlay, unit_type, unit_worth, units, unlock_view, unpetrify, unstore_unit, unsynced;


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


while, wml_message, wml_schema;



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.
  • unit_type: only apply this effect if the affected unit's type name matches the value. (can be a list)
  • unit_gender: only apply this effect if the affected unit's gender name matches the value. (can be a list)
  • 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_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.
    • 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.
  • 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 "true", 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 unit chance to be hit in specific terrain (100 - defense value)
    • replace: If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
    • [defense]: a subtag that describes the new defense just like in UnitsWML
  • resistance: Sets percent damage taken from combat
    • replace: If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
    • [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 (0=disable, other=enable).
  • 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.
  • Template:DevFeature1.11 halo: Change the image used for the unit's halo.
    • halo: the new image to use.
  • Template:DevFeature1.11 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.

See Also