From The Battle for Wesnoth Wiki
Revision as of 13:39, 18 July 2019 by Josteph (talk | contribs) ([movetype]: Add screenshot example of jamming)

[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, checkbox, choice, 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 (credits, options), 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, found_item, for, foreach, frame;


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, intro), illuminates, image (intro, terrain), 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, 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, 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 [units] tag is a top-level WML tag which defines the unit types that will be available in the game.

A [units] tag primarily contains [unit_type] tags, each of which defines one unit type, and can also contain other tags, which mostly provide definitions of things like races and movement types that are used in unit type definitions.

Subtags of [units]

The following tags can be used as subtags of a [units] tag.


Main article: UnitTypeWML

In a [units] tag, a [unit_type] tag defines a unit type.


The [trait] tag describes a trait. When it appears in the [units] toplevel, it describes a global trait, and all races with the attribute ignore_global_traits=no will have this trait.; it may also appear in other places.

  • id: unique identifier
  • availability: describes whether a trait is "musthave" for a race or is available to "any" unit in a race, including leaders, or "none" if it is not normally available, but should be kept when advancing to this unit type. (Traits not available to the advanced unit type at all, are permanently lost upon advancement.) The default is for a trait to only be available to nonleaders. Currently "any" should not be used for traits available in multiplayer. It can be used for campaign specific traits. (Note that currently "musthave" is somewhat misused to have what are really abilities (undead and mechanical) default from a unit type's race. Ideally someone will eventually extend race to allow for default abilities. It might also be possible to unify traits and abilities with keys to indicate how you get them and what happens to them when you advance, while allowing them to come from race, unit type and unit definitions. There are also display issues related to doing this.)
  • male_name: text displayed in the status of unit with the trait if the unit is male.
  • female_name: text displayed in the status of unit with the trait if the unit is female.
  • name: text displayed in the status of unit with the trait if none of the two above is used.
  • description: text displayed for the description of the trait when moving the cursor over the trait.
  • help_text: (Version 1.13.6 and later only) text displayed for the description of the trait in the help. Defaults to description if not specified.
  • [effect]: described in EffectWML. More than one of these can be used.


The [movetype] tag is used to make shortcuts to describe units with similar terrain handicaps. Units from the same advancement tree should generally have the same movetype.

  • name: an ID for this movetype. Units with the attribute movement_type=name will be assigned this movetype.
  • flies: either 'true' or 'false'(default). A unit with flies=true does not have its image's height adjusted for different terrains.
  • [movement_costs]: describes how fast the unit moves on different terrains. The attribute terrain=speed means that the unit will need to use speed move points to move onto terrain with id=terrain (see TerrainWML).
  • [vision_costs]: describes how far the unit clears fog and shroud on different terrains. The attribute terrain=cost means that the unit will need to use cost vision points to view into terrain with id=terrain (see TerrainWML). (If not specified for a particular terrain, the vision cost defaults to the movement cost.)
  • [jamming_costs]: (Version 1.13.0 and later only) describes how far the unit interferes with the vision of other units over different terrains. This works the same as movement and vision costs. Example of jamming
  • [defense]: describes how likely the unit is to be hit on different terrains. The attribute terrain=defense means that the unit will be hit defense percent of the time in the terrain with id=terrain. If the defense value is negative, then the unit will be hit as though the value were positive with one difference: the number is also the best defense that the unit may have if there is more than one terrain type for the terrain the unit is on.
  • [resistance]: describes how much damage the unit takes from different types of attacks. The attribute type=resistance makes the unit receive resistance percent of damage, or resist 100-resistance percent of damage from attacks with type=type. So for example, a resistance of fire=110 means, this unit will receive 110% of damage, or have a resistance of -10% as displayed in-game. A value of fire=0 would mean, the unit receives no damage and therefore has a resistance of 100%.

Default keys for the [movement_costs], [vision_costs], and [defense] tags are deep_water, shallow_water, reef, swamp_water, flat, sand, forest, hills, mountains, village, castle, cave, frozen, unwalkable, fungus, and impassable. Default keys for [resistance] are blade, pierce, impact, fire, cold, and arcane.


The [race] tag is used to make shortcuts to describe units with similar names. Units from the same advancement tree should generally have the same race. Also, units with the same race should generally be recruitable by the same sides/factions.

  • id: ID for this race. Units with the attribute race=id will be assigned this race. In older versions of WML, the value of the name key was used as id if the id field was missing, but this is no longer the case.
  • plural_name: user-visible name for its people (e.g. "Merfolk" or "Elves"). Currently only used in the in-game help.
  • male_name: user-visible name for the race of the male units (e.g. "Merman"). Currently only used in the in-game unit status.
  • female_name: user-visible name for the race of the female units (e.g. "Mermaid"). Currently only used in the in-game unit status.
  • name: the default value for the three keys above. The 'name' key is the default for 'male_name' and 'female_name'. 'id' and 'plural_name' must be supplied.
  • description: description of this race, used in the race page of the in-game help. Note: currently not used by all mainline races because their descriptions are not ready. But this is already supported by the engine.
  • name_generator (Version 1.13.5 and later only): Context-free grammar describing unit names, if absent or invalid, falls back to male_names or female_names
  • male_name_generator (Version 1.13.5 and later only): Like name_generator, but specific for male names
  • female_name_generator (Version 1.13.5 and later only): Like name_generator, but specific for female names
  • male_names, female_names: lists of names (i.e. non-translatable strings). They are inputted into the Markov name generator to generate random names. male_names describes units with gender=male; female_names describes units with gender=female.
  • markov_chain_size: (default 2) number of letters per "syllable". "Syllables" are groupings of names that the Markov name generator uses to determine names. It does this by running a probability algorithm to guess from the name list which syllables fit well together, which can start or end a name, etc.
  • num_traits: is the number of non-repeating traits each unit of this race can be assigned.
  • ignore_global_traits: 'yes' or 'no' (default). Determines whether global traits (see [traits] above) are applied.
  • undead_variation: sets the default undead variation for members of this race.
  • [topic]: describes extra help topics for this race.
  • [trait]: describes a trait for this race. See above for syntax.


(Version 1.13.2 and later only)

The [resistance_defaults] tag allows you to add resistance for custom damage types to already-defined movetypes (such as core movetypes).

  • id: The damage type you want to apply resistance defaults for.
  • default: The default resistance for all movetypes. You can set it to a number, or to a formula (enclosed in parentheses) which can reference any of the default resistance types - arcane, fire, etc. A common usage for formulas might be to set it to be equal to another resistance, eg default="(impact)".
  • Other keys reference the name= attribute of a defined movetype. For example, 'smallfoot=50' will set the resistance to 50 for the smallfoot movement type. Note: The default= key and other keys are handled slightly differently. A default= value will never override an explicitly specified value either in the same [resistance_defaults] tag or in a [movetype] definition, but other keys always take priority over values specified in a [movetype] definition.


(Version 1.13.2 and later only)

The [terrain_defaults] tag allows you to add costs and defenses for custom terrain types to already-defined movetypes (such as core movetypes).

  • id: The id= attribute of the terrain type you want to apply cost and defense defaults for.
  • [movement], [defense], [jamming], [vision] - Specify the default values using the same syntax as [resistance_defaults] - an optional default key, and subsequent keys which are movetype names. As with [resistance_defaults], you can use formulas if you enclose them in parentheses.


The [hide_help] tag allows you to hide some units from the help. Mainly useful if you can't change these units (e.g. mainline units) and thus can't add a 'hide_help=yes' key to them. Only really useful for campaigns, not for eras. The following keys and their contents uses an 'OR' logic between them.

  • type: list of unit types.
  • race: list of races. Equivalent to all unit types of these races.
  • type_adv_tree: list of unit types. Equivalent to all these types and their advancement trees.
  • all: 'yes' or 'no' (default). 'yes' is equivalent to all unit types (useful before [not])
  • [not]: all the previous keys (except 'all') can also be used in [not] sub-tags. And you can use [not] recursively. For example, if you want to only show the Yeti and the human race except the mage tree, use:

See Also