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;

The [unit_type] tag

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.

The following key/tags are recognized:

[advancefrom]	the previous level unit 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. 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 is optional. If present the experience needed to advance is set to this value. (Template:DevFeature1.9, in 1.8 it can only be lowered) 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.
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.
alignment	one of lawful/neutral/chaotic/liminal (See TimeWML). Default is "neutral".
attacks	the number of times that this unit can attack each turn.
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.
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.
ellipse	the ellipse image to display under the unit, which is normally team-colored. Default is the normal ellipse; "misc/ellipse-nozoc" is a dashed ellipse that should be used for units without zone of control.
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.
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.
hide_help	determines if the unit type will appear in the in-game help. Possible values true and false, defaults to false.
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. An id should consist only of alphanumerics and spaces (or underscores). type keys are found in SingleUnitWML and FilterWML. For example, id=Drake Flare WARNING : characters "$", "&", "*", "(" and ")" are illegal for use in the unit id and must be avoided because they might lead to corrupted saved games
image	FIXME - What does [unit_type]image= do?
image_icon Template:DevFeature1.9	sets the image used to represent the unit in areas such as the attack dialog and the unit image box in the sidebar
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).
movement	the number of move points that this unit receives each turn.
movement_type	See movetype, UnitsWML. Note that the tags movement_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.
small_profile Template:DevFeature1.9	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. 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], UnitsWML. Also used in standard unit filter (see FilterWML).
undead_variation	Which image to use when a unit of this type is killed by a unit with the plague ability. Defaults to the undead_variation set in this unit type's race. Template:DevFeature1.9
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 affects only recruitment, not the AI's behavior in combat; that is always computed from attack power and hitpoints.
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).

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.
  • always_display: if set to true displays the AMLA option even if it is the only available one.
  • description: a description (see DescriptionWML) 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.
  • 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.
  • [effect]: A modification applied to the unit whenever this advancement is chosen. See EffectWML

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 (if name=x then icon=attacks/x.png is assumed unless present). 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 [resistances], UnitsWML).
  • [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.
  • range: the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. Also displayed on the status table in parentheses; 'melee'(default) displays "melee", while 'ranged' displays "ranged". Range can be anything. Standard values are now "melee" and "ranged". From now on, short and long will be treated as totally different ranges. You can create any number of ranges now (with any name), and units can only retaliate against attacks for which they have a corresponding attack of the same range. This value is translatable.
  • damage: the damage of this attack
  • number: the number of strikes per attack this weapon has
  • 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.

For those two following settings, the engine usually chooses the attack with the best average total damages * weight (default weight = 1.0).

• • attack_weight: helps the AI to choose which attack to use when attacking; highly weighted attacks are more likely to be used. Setting it to 0 disables the attack on attack
  • 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

Animations

See AnimationWML for details on how to specify animations for the unit.

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. Subsequent attributes modify the copy. (1.3.7 and later versions only.)

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

• [variation]: Defines a variation of a unit. Variations are invoked with an [effect] tag. They are currently used for graphical variations (giving character sprites new weapons) but theoretically you could do anything with it.
  • variation_name: The name of the variation.
  • inherit: if yes, inherits all the properties of the base unit. Defaults to no.

All other keys in [variation] are the same as for [unit_type] itself.

• [male], [female]: They can contain all [unit_type] tags, to specify a variation of different gender for a unit.
  • inherit: if yes, inherits all the properties of the base unit. Defaults to yes.

See Also

• AnimationWML
• ReferenceWML
• TerrainWML