UnitsWML

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

[unit_type]

Main article: UnitTypeWML

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

[trait]

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. 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.
• 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.
• [require_traits]: (Version 1.17.13 and later only) An optional comma-separated list of trait id keys that represent traits that are required by this one. Order is not important. If the unit not already has all of the traits that appear in this list, then this trait will not be generated for this unit.
• [exclude_traits]: (Version 1.17.13 and later only) An optional comma-separated list of trait id keys that represent traits that are mutually exclusive to this one. Order is not important. If the unit already has any of the traits that appear once in this list, then this trait will not be generated for this unit. Of course, for this to really make two traits mutually exclusive, you need to add exclude_traits to both trait definitions.

[movetype]

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 or (Version 1.15.0 and later only) flying: either 'yes' or 'no' (default). A unit with flying=yes does not have its image's height adjusted for different terrains.
  • This key corresponds to [unit]'s flying key.
  • In Wesnoth 1.12 and 1.14, the value of flying sometimes overrides the value of flies, but in other times flying is ignored
  • (Version 1.15.0 and later only) flying always overrides the flies value, with the intention that flies will be deprecated.
• [special_note] (Version 1.15.14 and later only) Translatable string, which can be set if there’s something special about this movetype. It will be displayed in the unit's help page. For typical movetypes this is not set. An example are horses with the mounted movetype. See also UnitTypeWML#Special_Notes.
• [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.

[race]

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: text used in the in-game help.
• help_taxonomy: (Version 1.15.5 and later only) in the help browser, show this race as a group of units from another race; the value of this attribute should be the other race's id attribute. This only affects the help browser, for all other purposes (such as WML filters) the two races are completely separate. (How this is visualised in the help browser is a GUI design decision, this attribute merely tells the engine that the relationship exists.)
• 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.

[resistance_defaults]

Note: broken in 1.14.8, fixed in 1.14.16 and 1.15.9 (issue #5308)

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, but with no preceding dollar sign $) 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. Formulas can also be used here, for example 'smallfoot=(impact)'.

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.15.9 and later only) The formulas can now access other parts of the movetype, for example "(resistance.arcane)" or "(movement_costs.flat)". For [resistance_defaults], "(arcane)" is shorthand for, and equivalent to, "(resistance.arcane)". See the documentation in the [terrain_defaults] section for more details about this.

[terrain_defaults]

Note: broken in 1.14.8, fixed in 1.14.16 and 1.15.11 (issue #5308)

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.
• Subtags are used to specify the 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 (but with no preceding dollar sign $).
• Short names for the subtags are [movement], [jamming], [vision], and [defense].
• Long names for the subtags are [movement_costs], [vision_costs], [jamming_costs], and [defense].

1.14.16 and 1.15.11 recognise both the short and long names above. 1.15.9 and 1.15.10 only recognised the long names, and all other prior versions only recognised the short names.

(Version 1.14.16 and later only) (Version 1.15.9 and later only) The formulas can now access other parts of the movetype, for example (resistance.arcane) or (movement_costs.swamp_water). Simply using (swamp_water) is shorthand for the value in whichever subtag is being patched. Formulas only recognise the long names.

The [terrain_defaults] tags are processed before any calculations of mixed terrains happen, and can only access the values for the basic terrain types. It's not useful to set a value for a mixed terrain type, as the calculations of mixed terrains' values decompose the mixed terrain to its base terrains before calculating the result, thus ignoring any patched values for mixed terrains.

Setting a default= value for [vision_costs] or [jamming_costs] means that that value will be used instead of falling back to using the movement_costs for calculating vision. For this reason, it's likely that default= should only be used when patching the [movement_costs] and [defense], not for vision or jamming.

A formula may use data added in a previous [terrain_defaults]. However, relying on data in the same [terrain_defaults] that creates or changes it is unsupported, because no guarantee is made of the order in which the subtags are processed.

While [terrain_defaults] formulas can use resistances, and [resistance_defaults] formulas can use movement costs, no guarantee is made of whether [terrain_defaults] tags will be processed before or after [resistance_defaults] tags. Therefore, formulas should only use base terrains and not rely on data added by the other kind of movetype-patching tag.

[hide_help]

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:

[hide_help]
    all=yes
    [not]
        type=Yeti
        race=human
        [not]
            type_adv_tree=Mage
        [/not]
    [/not]
[/hide_help]

See Also

• UnitTypeWML
• ReferenceWML