UnitTypeWML

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

Unit Type

Each [unit_type] tag defines one unit type. (for the use of [unit] to create a unit, see SingleUnitWML)

Unit animation syntax is described in AnimationWML. In addition to the animation tags described there, the following key/tags are recognized:

• advances_to: When this unit has experience greater than or equal to experience, it is replaced by a unit of the type that the value of advances_to refers to. All modifications that have been done to the unit are applied to the unit it is replaced by. The special value 'null' says that the unit does not advance but gets an AMLA instead. Can be a comma-separated list of units that can be chosen from upon advancing.
• alignment: one of lawful/neutral/chaotic/liminal (See TimeWML). Default is "neutral".
• attacks: the number of times that this unit can attack each turn. Default is 1.
• cost: when a player recruits a unit of this type, the player loses cost gold. If this would cause gold to drop below 0, the unit cannot be recruited. Default is 1.
• recall_cost: (Version 1.13.0 and later only) the default recall cost of units of this type, overriding the recall cost set in scenario [side] tags or the global [game_config] value. Individual units may override this value in [unit]. A value of -1 is equivalent to not specifying this attribute. (Version 1.15.0 and later only) Units are now recalled for AI sides even if the recall_cost is larger than the unit's worth (essentially its cost, plus potentially a bonus for experience points). In 1.14 and earlier, units were not recalled by the AI in this case even if this was the only recall/recruit action possible to the AI.
• description: (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
• do_not_list: Not used by the game, but by tools for browsing and listing the unit tree. If this is 'yes', the unit will be ignored by these tools. (Version 1.13.? and later only) When placing units in debug mode this unit isn't listed (but can still be placed using the :create command). This restriction is lifted in version 1.14.3.
• ellipse: the ellipse image to display under the unit, which is normally team-colored. Default is "misc/ellipse". "-nozoc" and "-leader" are automatically appended for units without zone of control and with canrecruit=yes respectively. The IS_HERO/MAKE_HERO/UNMAKE_HERO macros change the ellipse to/back from "misc/ellipse-hero". Finally, setting this to "none" will cause the unit to not have any ellipses displayed under it regardless of the user's preferences.
  WARNING: Be aware that setting this to "misc/ellipse-hero" for a unit with canrecruit=yes will result in the ellipse being "misc/ellipse-hero-leader", which is not a supported combination (it doesn't have a graphic, and will cause error logs that the graphic is missing). This is tracked as bug 6258 on GitHub.
  (Version 1.17.26 and later only) canrecruit=yes is now supported with "misc/ellipse-hero", since "misc/ellipse-hero-leader" has been added in 8375.
• experience: When this unit has experience greater than or equal to experience, it is replaced by a unit with 0 experience of the type that the value of advances_to refers to. All modifications that have been done to the unit are applied to the unit it is replaced by.
• flag_rgb: usually set by MAGENTA_IS_THE_TEAM_COLOR; specifies the colours in the base flag to use for team-colouring the unit, expressed as a colour name (such as magenta) or a comma-separated list of RGB values (in hex format).
• gender: has a value of either male or female, and determines which of the keys male_names and female_names should be read. When a unit of this type is recruited, it will be randomly assigned a name by the random name generator, which will use these names as a base. If gender is not specified it defaults to male.
• halo: an image to place centered on the unit. It is drawn on top of the unit, and on top of surrounding units if the image is larger than one hex. It works similarly to the halo attribute of [item], and it can be animated with a comma-separated list of images.
• hide_help: (yes|no) default=no. Determines if the unit type will appear in the in-game help.
• hitpoints: the maximum HP that the unit has, and the HP it has when it is created.
• id: the value of the type key for units of this type. This is required and must be unique among all [unit_type] tags. An id must consist only of alphanumerics and spaces (or underscores). type keys are found in SingleUnitWML and FilterWML. For example, id=Drake Flare
• ignore_race_traits: 'yes' or 'no' (default). Determines whether racial traits (see UnitsWML) are applied.
• image: sets the base image of the unit, which is used on the map.
• image_icon: sets the image used to represent the unit in areas such as the attack dialog and the unit image box in the sidebar. ~CROP function can be useful here. You can see Loyalists Paladin as an example.
• level: the amount of upkeep the unit costs. After this unit fights, its opponent gains level experience. See also kill_experience (GameConfigWML), and leadership (AbilitiesWML).
• upkeep: the amount of upkeep the unit costs if it differs from its level.
• movement: the number of move points that this unit receives each turn.
• movement_type: See movetype. Note that the tags [movement_costs], [vision_costs], [defense], and [resistance] can be used to modify this movetype.
• name: (translatable) displayed in the Status Table for units of this type.
• num_traits: the number of traits that units of this type should receive when they are recruited, overriding the value set in the [race] tag.
• profile: the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see SingleUnitWML). The engine first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. Depending on the size the engine will or will not scale the image, the cutoff currently is at 300x300. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.
  • If "unit_image" is given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).
  • If "none" is given instead of a filename, no image will be displayed.
• small_profile: the image to use when a smaller portrait is needed than the one used for messages (e.g., in the help system). When this attribute is missing, the value of the profile attribute is used instead. When present, the heuristic for finding a transparent portrait is disabled for the profile attribute, so the correct profile should be set too. If profile is not present, small_profile is ignored. Note that image modifiers are allowed; they might be useful for cropping and rescaling a portrait:

small_profile="portraits/elves/transparent/marksman+female.png~CROP(0,20,380,380)~SCALE(205,205)"
profile="portraits/elves/transparent/marksman+female.png"

• race: See [race]. Also used in standard unit filter (see FilterWML). Mainline Wesnoth features following values: bats, drake, dwarf, elf, falcon, goblin, gryphon, human, dunefolk, lizard, mechanical, merman, monster, naga, ogre, orc, troll, undead, wolf, wose. They are defined in /data/core/units.cfg.
• undead_variation: When a unit of this type is killed by a weapon with the plague special, this variation is applied to the new plague unit that is created, whatever its type. For example, if the plague special creates Walking Corpses and undead_variation is set to "troll", you'll get a troll Walking Corpse. Defaults to the undead_variation set in this unit type's race.
• usage: the way that the AI should recruit this unit, as determined by the scenario designer. (See recruitment_pattern, AiWML). The following are conventions on usage:
  • scout: Fast, mobile unit meant for exploration and village grabbing.
  • fighter: Melee fighter, melee attack substantially more powerful than ranged.
  • archer: Ranged fighter, ranged attack substantially more powerful than melee.
  • mixed fighter: Melee and ranged fighter, melee and ranged attacks roughly equal.
  • healer: Specialty 'heals' or 'cures'.

Note that this field primarily affects recruitment. It also has a small effect on unit movement (the AI tries to keep scouts away from enemies, to some extent). It does not affect the AI's behavior in combat; that is always computed from attack power and hitpoints. Non-standard usages may be used as well.

• vision: the number of vision points to calculate the unit's sight range. Defaults to movement if not present.
• jamming: the number of jamming points. Defaults to 0 if not present. See [jamming_costs]
• zoc: if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).
• die_sound: sets the sound, which is used when the unit dies.
• healed_sound: sets the sound used when the unit is healed in any way (default: heal.wav).
• hp_bar_scaling: Overrides the attribute in (GameConfigWML).
• xp_bar_scaling: Overrides the attribute in (GameConfigWML).
• bar_offset_x, bar_offset_y: The offset of the hp and xp bars from the normal bar position of 72x72 unit sprite.

After max level advancement (AMLA)

• [advancement]: describes what happens to a unit when it reaches the XP required for advancement. It is considered as an advancement in the same way as advancement described by advances_to; however, if the player chooses this advancement, the unit will have one or more effects applied to it instead of advancing.
  • id: unique identifier for this advancement; Required if there are multiple advancement options, or if strict_amla=no.
  • always_display: if set to true displays the AMLA option even if it is the only available one.
  • description: a description displayed as the option for this advancement if there is another advancement option that the player must choose from; otherwise, the advancement is chosen automatically and this key is irrelevant.
  • image: an image to display next to the description in the advancement menu.
  • max_times: default 1. The maximum times the unit can be awarded this advancement. Pass -1 for "unlimited".
  • strict_amla: (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.
  • major_amla: (yes|no) default=no. Sets whether the unit's XP bar is blue(=yes) or purple(=no). In case of more [advancement] tags, if there is one with major_amla=yes, the XP bar will be blue.
  • require_amla: An optional list of AMLA id keys that act as prerequisites for this advancement to become available. Order is not important, and an AMLA id can be repeated any number of times to indicate that another advancement must be chosen several times before this advancement option will become available.
    • example: require_amla=tough,tough,incr_damage assumes there exist other [advancement] options called id=tough and id=incr_damage. Once tough is chosen twice and incr_damage is chosen once, then the current [advancement] will become available.
    • require_amla=tough,incr_damage,tough is an equivalent way of expressing this.
  • exclude_amla: (Version 1.13.2 and later only) An optional list of AMLA id keys that represent AMLAs that are mutually exclusive to this one. Order is not important, and an AMLA id can be repeated. If the unit already has any of the AMLAs that appear once in this list, then this AMLA will not be made available. If an AMLA id appears multiple times in the list, then this AMLA will be made available only if the other AMLA has been chosen less than the number of times it appears in the list. Of course, for this to really make two AMLAs mutually exclusive, you need to add exclude_amla to both AMLA defintions.
  • [effect]: A modification applied to the unit whenever this advancement is chosen. See EffectWML
  • [filter]: A StandardUnitFilter, the advancement will only be available when the unit passes this filter during the time the advancement dialog is shown.

Attacks

• [attack]: one of the unit's attacks.
  • description: a translatable text for name of the attack, to be displayed to the user.
  • name: the name of the attack. Used as a default description, if description is not present, and to determine the default icon, if icon is not present (see below). Non-translatable. Used for the has_weapon key and animation filters; see StandardUnitFilter and AnimationWML
  • type: the damage type of the attack. Used in determining resistance to this attack (see [resistance]). Usually this is one of blade, pierce, impact, fire, cold, or arcane, but it can be set to anything (as long as it contains only letters, numbers, and underscores). When using a custom type, you will need to set its user-visible name using LanguageWML. (Version 1.15.0 and later only) When showing the icon for a custom damage type in the sidebar, the game will look for a file called icons/profiles/type.png under your addon's images folder. For example, the icon for a damage type called electric would be at images/icons/profiles/electric.png.
  • [specials]: contains the specials of the attack. See AbilitiesWML.
  • icon: the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory. Defaults to the attack's name in the attacks directory (Ex. if name=sword then default is icon=attacks/sword.png).
  • range: the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. The range can be anything (as long as it contains only letters, numbers, and underscores), but the standard values are melee and ranged. Units can only retaliate against attacks for which they have a corresponding attack of the same range. When using a custom range, you will need to set its user-visible name using LanguageWML. (Version 1.15.0 and later only) When showing the icon for a custom range in the sidebar the game will look for a file called icons/profiles/range_attack.png under your addon's images folder. For example, the icon for a range called very_long would be at images/icons/profiles/very_long_attack.png.
  • max_range: maximum distance (in number of hexes) to which this attack works. Default is 1.
    • This currently lacks UI and AI support.
  • min_range: minimum distance (in number of hexes) to which this attack works. Default is 1.
    • This currently lacks UI and AI support.
  • damage: the damage of this attack
  • number: the number of strikes per attack this weapon has
  • accuracy: a number added to the chance to hit whenever using this weapon offensively (i.e. during a strike with this attack, regardless of who initiated the combat); negative values work too
  • parry: a number deducted from the enemy chance to hit whenever using this weapon defensively (i.e. during the enemy's strike, regardless of who initiated the combat); negative values work too
  • movement_used: determines how many movement points using this attack expends. By default all movement is used up, set this to 0 to make attacking with this attack expend no movement.
  • attacks_used: (Version 1.17.12 and later only) determines how many attacks this attack expends (default 1). This number is deducted from the unit's attacks_left when they use this attack.
  • attack_weight: multiplier for total damage that the AI should use to choose which attack to use when attacking (and offer to player as default). Setting it to 0 disables the attack on attack. Until (Version 1.19.2 and later only) positive attack_weight was ignored.
  • defense_weight: used to determine which attack is used for retaliation. This affects gameplay, as the player is not allowed to determine his unit's retaliation weapon. Setting it to 0 disable the attacks on defense.
  • alignment: (Version 1.19.5 and later only) one of lawful/neutral/chaotic/liminal (See TimeWML). Default is unit alignment.

Other tags

• [base_unit]: Contains one attribute, id, which must be the ID of a unit type. If specified, the UnitTypeWML for that unit is copied into this one, as if by [set_variables]mode=merge. Additionally, the unit will be marked as variation of the base unit in its own help page, but not in the help page of the base unit.

• [abilities]: Defines the abilities of a unit. See AbilitiesWML

• [event]: Any [event] written inside the [unit_type] tag will get included into any scenario where a unit of this type appears in. Note that such events get included when a unit of this type first appears in the scenario, not automatically when the scenario begins (meaning that name=prestart events, for example, would usually never trigger). See EventWML and WML Abilities. (Version 1.19.4 and later only) Abilities support [event].

• [variation]: Defines a variation of a unit. Variations are invoked with an [effect] tag or the variation= attribute in SingleUnitWML. They are currently used for graphical variations (giving character sprites new weapons) but theoretically you could do anything with it.
  • variation_id: Mandatory. The value of variation= used in SingleUnitWML to choose this variant.
  • variation_name: Translatable. The name of the variation, which is displayed in the help and in debug mode. Not setting this looks bad unless combined with hide_help=yes.
  • inherit: if yes, inherits all the properties of the base unit, as if by [set_variables]mode=merge. Defaults to no.
    • The id key is always inherited, regardless of the value of inherit.
  • All keys and tags of [unit_type], except [advancefrom], [base_unit], [female], [male], and [variation].

• [male], [female]: These can specify a variation based on gender for a unit. If these are provided, they will automatically apply based upon the gender of a unit.
  • inherit: if yes, inherits all the properties of the base unit, as if by [set_variables]mode=merge. Defaults to yes.
    • The id key is always inherited, regardless of the value of inherit.
  • All [unit_type] tags and keys, excluding [advancefrom], [base_unit], [female], and [male].
• [trait]: Adds an additional trait to the pool. See UnitsWML for the syntax.
• [special_note] (Version 1.15.2 and later only) see below.

Special Notes

Use of the [special_note] tags and attributes results in a bulleted list of special notes in the unit type's help page and in the sidebar tooltip for the unit type's name. Prior to 1.15.2, the old format for special notes was simply text included in the [unit_type]description attribute.

Note that the sidebar tooltip shows the notes for the current unit, but opening the help-browser by right-clicking on a unit shows the notes for generic units of that type. These can be different if the unit has [modifications].

Text given in the following attributes will be collected and shown as the special notes for units and unit types:

• (Version 1.15.2 and later only) [unit_type][special_note]note=
• (Version 1.15.2 and later only) [unit][special_note]note= (these are used instead of any defined in the [unit_type])
• (Version 1.15.14 and later only) [movetype][special_note]note=
• (Version 1.15.14 and later only) [ability tag name]special_note=
• (Version 1.15.14 and later only) [attack][specials][special tag name]special_note=
• (Version 1.15.14 and later only) [language]special_note_damage_type_TYPE=

It's no longer necessary to put these notes in each unit_type's .cfg file, and the macros for doing so are now deprecated.

Removed keys

These don't work any more, the documentation is left here as an aid to porting old code.

• [advancefrom]: (Version 1.15.4 and later only) replaced by [modify_unit_type]. Defines the previous unit type on the advancement tree. Allows a campaign-specific unit to be spliced into an already existing advancement tree. It should generally be used only inside a campaign ifdef, to prevent changes to other campaigns. Since all multiplayer content shares MULTIPLAYER define, using advancefrom changes unit type even if the addon is not actively used. For that reason multiplayer advancefrom may only be used with unit types defined in the same addon - then everyone who has the unit has it with same advancements. This tag makes changes to the advances_to and experience keys of a base unit to make it advance into this unit. It takes these keys:
  • unit: the id of the base unit from which this unit advances. This adds the unit into the list of units which unit can advance into.
  • experience: (optional) If present the experience needed to advance is set to this value. If there are more than one [advancefrom] tags referencing the same base unit within the same preprocessor scope (e.g. a campaign #ifdef) with experience= keys, the lowest value of these is chosen. Note: this will also lower the experience required to advance to other units which the base unit can advance into.

If the previous unit type makes use of [male] and/or [female] tags, then the current (new) unit type is expected to also. That is, the subtypes defined by those tags will only receive this advancement if the new type has a corresponding tag.

(Version 1.15.4 and later only) [advancefrom] was effectively removed in 1.15.4. The intention was to deprecate it, but the compatibility code that was meant to support it in 1.16 was untested and nonfunctional.

Deprecating units

A macro is provided for deprecating a unit, which uses the built-in deprecation system but hard-codes the level to 3 (meaning "for removal"). The syntax is:

{DEPRECATED_UNIT old_id new_id version}

You can also set the new_id to an empty string if there is no replacement.

See Also

• AnimationWML
• ReferenceWML
• TerrainWML