Difference between revisions of "SingleUnitWML"

From The Battle for Wesnoth Wiki
(How to describe a single unit: this is documented on game config but not here.)
(major edit restructuring the page into persistent, state, and creation data, also some rewording here and there to clarify some things and remove inaccuracies.)
Line 1: Line 1:
 
{{WML Tags}}
 
{{WML Tags}}
== How to describe a single unit ==
+
The '''[unit]''' tag describes a single unit on the map or in memory, for example Konrad.
 
 
This tag, '''[unit]''', describes a single unit on the map, for example Konrad.
 
 
It is different from the [unit_type] in [units], which describes a class of units. However it takes many of the same keys and thus can generally override the inherited properties from the associated [unit_type].
 
It is different from the [unit_type] in [units], which describes a class of units. However it takes many of the same keys and thus can generally override the inherited properties from the associated [unit_type].
  
 
[unit] can be used inside [side] ([[SideWML]]) for units present at start of the scenario, or as [[DirectActionsWML]] for units created during the game. (It is also used in save-files.)
 
[unit] can be used inside [side] ([[SideWML]]) for units present at start of the scenario, or as [[DirectActionsWML]] for units created during the game. (It is also used in save-files.)
  
The following keys are recognized:
+
== Unit Data ==
* '''type''': the ID of the unit's unit type. See [[UnitTypeWML]].
+
The following keys and tags describe the unit itself, and will persist with the unit (though some may change automatically when the unit advances):
 +
* <span id="type">'''type'''</span>: the ID of the unit's unit type. This key is mandatory. See [[UnitTypeWML]].
 +
 
 +
* '''variation''': the [variation] of the [unit_type] as which the unit will appear.
  
 
* '''parent_type''': overrides '''type''' if this is present. This is likely of little use to WML authors; it is automatically generated when needed by the game (to keep track of some [unit_type][variation]s).
 
* '''parent_type''': overrides '''type''' if this is present. This is likely of little use to WML authors; it is automatically generated when needed by the game (to keep track of some [unit_type][variation]s).
  
* '''side''': the side that the unit is on. It has to be an existing side, even if the unit is created in a variable.
+
* '''side''': the side that the unit is on. It has to be an existing side, even if the unit is created in a variable. Mandatory except when the [unit] tag appears inside a [side], in which case it defaults to that side.
 
 
* '''gender''': can be set to male or female to designate the gender of the unit. Default is male, but if the unit has only a female variant it will be female.
 
 
 
* '''x''', '''y''': the location of the unit. By default ( see '''placement''') if a location isn't provided and the side the unit will belong to has a recall list, the unit will be created on the recall list.
 
 
 
* '''placement''': How the unit should be placed: can be one value or a comma-separated list of values. Default value is  'map,leader' for a leader given directly in [side], "" otherwise. By default, 'map,recall' is implicitly appended to the end of the list.
 
** '''map''': If x,y are explicitly given and point to a valid on-map location - try to place the unit at the nearest free location to there, never overwriting existing units. Successful if x,y are given and a valid on-map vacant location near it can be found.
 
** '''leader''': Try to place unit near the leader, if leader is not present or is in recall list - try to place unit near the start location for this side. Successful if a valid on-map vacant location can be found near leader or near start location.
 
** '''recall''': Place unit on recall list. Always successful.
 
** '''map_overwrite''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location, if there was a unit there - overwriting it, without firing events.
 
** '''map_passable''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location; if the hex is of an impassable terrain for the unit being placed, or is already occupied by another unit, the new unit will be placed in the nearest vacant hex.
 
** '''leader_passable''': Similar to "leader", with the additional restriction that the selected location is not impassable for the unit being placed.
 
 
 
* '''to_variable''': creates the unit into the given variable instead of placing it on the map.
 
 
 
* '''id''': a unique identifier for the unit. This is (usually) not displayed to the player, but is to be used only for identifying and filtering units. If not specified or when a unit is normally recruited, a random one will be generated for the unit to ensure that each unit has a unique ''id'' attribute.  In older versions, the '''description''' attribute specified a unique ID. (The one instance when an id is displayed to the player is when the leader's id is used as the default for a [[SideWML|side]]'s '''current_player''' attribute.)
 
 
 
* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this.
 
 
 
* '''generate_name''': (default=yes) will generate a new name if there isn't one specifed for the unit, as if the unit were a freshly-recruited one
 
  
* '''unrenamable''': if 'yes', the user-visible name of the unit cannot be changed by the player (which is only possible when the unit is on the player's side anyway).
+
* '''id''': a unique identifier for the unit. This is (usually) not displayed to the player, but is to be used only for identifying and filtering units. If not specified, a random one will be generated for the unit to ensure that each unit has a unique '''id''' attribute (as will happen when a unit is recruited normally). In older versions, the '''description''' attribute specified a unique ID. (The one instance when an id is displayed to the player is when the leader's id is used as the default for a [[SideWML|side]]'s '''current_player''' attribute.) Note: While it IS technically possible to create multiple units with the same ID, doing so may produce unpredictable results in many cases. WML should therefore be structured in such a way that no two units in existence ever end up with the same ID.
  
* '''traits_description''': the description of the unit's traits which is displayed. However if it is not specified explicitly, the unit's actual traits' names will be used instead, so it is normally not necessary to set this.
+
* '''gender''': can be set to male or female to designate the gender of the unit. Default is male (unless [[#random_gender|'''random_gender''']] is set to "yes"), but if the unit has only a female variant it will be female.
  
* '''random_traits''': "no" will prevent random trait generation for units. You should only need to set this for placed nonleaders in multiplayer games or if you want to give a unit less traits than it would normally get for its unit type. When generating traits for a unit, first traits the unit has already been given are excluded. Then "musthave" traits (undead, mechanical) for the unit type are given. Then for leaders ('''canrecruit=yes''') traits that are not available to "any" (currently that's all of them to avoid a multiplayer OOS issue, but later will be restricted based on multiplayer play balance issues) are removed from consideration. Then traits are added randomly until the maximum allowed for the unit type is reached or there are no more available traits. Random traits can now be used in MP games but only when spawned in an event, so not for leaders and other units in the [side] definition.
+
* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this (unless '''unrenamable''' is also set).
  
* '''random_gender''': "yes" will cause the gender of the unit with male and female variations to be male 50% of the time, female 50% of the time.  If the unit has only one gender variant it will always be given the correct one.
+
* <span id="unrenamable">'''unrenamable'''</span>: if 'yes', the user-visible name of the unit cannot be changed by the player (which is only possible when the unit is on the player's side anyway).
  
 
* '''canrecruit''': a special key for leaders.
 
* '''canrecruit''': a special key for leaders.
Line 48: Line 29:
 
: More than one unit with '''canrecruit=yes''' for the same side (see [[SideWML]]) are allowed in single player, if the side is human-controlled.
 
: More than one unit with '''canrecruit=yes''' for the same side (see [[SideWML]]) are allowed in single player, if the side is human-controlled.
  
* '''extra_recruit''': a list of unit types which this unit can recruit in addition to the ones given by its [side]recruit=, only working for units with '''canrecruit=yes'''.
+
* '''extra_recruit''': a list of unit types which this unit can recruit in addition to the ones given by its [side]recruit= (only relevant for units with '''canrecruit=yes''').
  
* '''variation''': the variation of itself the unit should be created as.
+
* '''[filter_recall]''' A leader can only recall those units which pass the SUF. (Meaningful only if canrecruit=yes.)
 +
**'''[[StandardUnitFilter]]''' tags and keys
  
* '''upkeep''': the amount of upkeep the unit costs.
+
* '''upkeep''': the amount of upkeep the unit will require each turn.
 
** '''loyal''': no upkeep cost. Can be changed by the effect 'loyal' (see [[EffectWML]])
 
** '''loyal''': no upkeep cost. Can be changed by the effect 'loyal' (see [[EffectWML]])
 
** '''free''': synonymous with "loyal".
 
** '''free''': synonymous with "loyal".
Line 63: Line 45:
 
* {{DevFeature1.13|0}} '''recall_cost''': the recall cost of this unit. Overrides the values specified by the unit's type ([[UnitTypeWML|[unit_type]]]), its side ([[SideWML|[side]]]), and the global [[GameConfigWML|[game_config]]] value. A value of -1 is equivalent to not specifying this attribute.
 
* {{DevFeature1.13|0}} '''recall_cost''': the recall cost of this unit. Overrides the values specified by the unit's type ([[UnitTypeWML|[unit_type]]]), its side ([[SideWML|[side]]]), and the global [[GameConfigWML|[game_config]]] value. A value of -1 is equivalent to not specifying this attribute.
  
* '''overlays''': a list of images that are overlayed on the unit.
+
* '''overlays''': a comma-separated list of images that are overlayed on the unit.
 +
 
 +
* <span id="max_hitpoints">'''max_hitpoints'''</span>: The maximum hitpoints the unit has when at full health. Default is the max HP set for the [unit_type] described by [[#type|'''type''']].
 +
 
 +
* '''max_experience''': The experience the unit needs to advance. Default is the experience required for the [unit_type] described by [[#type|'''type''']].
 +
 
 +
* <span id="max_moves">'''max_moves'''</span>: The maximum number of movement points the unit has. Default is the number of movement specified for the [unit_type] described by [[#type|'''type''']].
  
* '''goto_x''':, '''goto_y''': UI settings that control courses. Default is 0,0 i.e. the unit is not on a course.
+
* <span id="max_attacks">'''max_attacks'''</span>: The number of attacks the unit can have per turn. Default is the number of attacks specified for the [unit_type] described by [[#type|'''type''']].
  
* '''hitpoints''': the HP of the unit. Default is the max HP for ''type''.
+
* '''profile''': sets a portrait image for this unit. Default is the portrait image set for the [unit_type] described by [[#type|'''type''']]. When the unit advances, if the value of profile is different from the unit-type portrait, that value is preserved. If the profile field is empty or the same as the unit-type portrait, the level-advance changes the unit portrait to the default for the new level and type. See [[UnitTypeWML]] for the rules used for locating files.
 +
** 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).
  
* {{DevFeature1.13|6}} '''invulnerable''': a shorthand to set the ''invulnerable'' status.
+
* '''small_profile''': sets a small portrait image for this unit. See the '''profile''' attribute above for advancement and special values. As with [[UnitTypeWML]], the location heuristic of the '''profile''' attribute is disabled when the '''small_profile''' attribute is provided.
  
* '''hp_bar_scaling''': Overwrites the attribute in ([[GameConfigWML]]).
+
* '''role''': used in standard unit filter ([[FilterWML]]). Can be set using [role] (see [[InternalActionsWML]]).
  
* '''xp_bar_scaling''': Overwrites the attribute in ([[GameConfigWML]]).
+
* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).
  
* '''experience''': the XP of the unit. Default is 0.
+
* '''[modifications]''' changes that have been made to the unit.
 +
** '''[trait]''' a trait the unit has. Same format as [[UnitsWML#[trait]|[trait], UnitsWML]].
 +
** '''[object]''' an object the unit has. Same format as [[DirectActionsWML#[object]|[object], DirectActionsWML]].
 +
** '''[advance]''' an advancement that has already been applied to the unit. Same format as [[UnitTypeWML#After max level advancement (AMLA)|AMLA [advancement], UnitTypeWML]]. These are automatically added as the unit has AMLA advancements applied to it, but can also be specified manually to indicate that the unit already has a particular advancement applied, or to disable certain advancements (by ID). {{DevFeature1.13|2}} In 1.13.2 and later this has been renamed to [advancement], to match the UnitTypeWML tag of the same name.
  
* '''moves''': number of movement points the unit has left. Default is the movement for its unit type.
+
* '''[event]''' The event is copied from this unit's WML description into the scenario. The event is carried along with the unit (even during advancement) and inserted into a scenario whenever this unit is first included. A [unit][event] requires a non-empty id= attribute.
: '''Note:''' Do not assume that moves=max_moves on turns when a unit doesn't move. The wesnoth AIs sometimes manipulate the moves variable during its turn, for internal reasons.
 
  
* '''attacks_left''': number of attacks the unit has left. Default is equal to the attacks key for its unit type, that usually is 1 (see ''max_attacks'' below).
+
* '''unit_description''': overrides the unit type description for this unit. Note that this will be reset when the unit advances. To avoid this, one can either set up a ''post_advance'' [[EventWML|event]] to override the default description after promotion, or use an [object] with a profile [[EffectWML|effect]] to change the unit description.
  
* '''resting''': whether the unit has not moved yet this turn. Used to decide whether to give a unit rest healing.
+
* '''hp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).
  
* '''role''': used in standard unit filter ([[FilterWML]]). Can be set using [role] (see [[InternalActionsWML]]).
+
* '''xp_bar_scaling''': Overrides the attribute in [[GameConfigWML]] (and the [unit_type], if present).
  
 
* '''ai_special''': causes the unit to act differently
 
* '''ai_special''': causes the unit to act differently
 
** "guardian" the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). Does the same as '''[status] guardian = 'yes''''.
 
** "guardian" the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). Does the same as '''[status] guardian = 'yes''''.
 +
 +
* '''[ai]''' This affects how the computer will control this unit (currently only used by [[FormulaAI]]).
 +
** '''formula''': if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side
 +
** '''priority''', '''loop_formula''', '''[vars]''': see the [[FormulaAI]] documentation for details
 +
 +
* '''traits_description''': the description of the unit's traits which is displayed. However if it is not specified explicitly, the unit's actual traits' names will be used instead, so it is normally not necessary to set this.
 +
 +
== Unit State ==
 +
The following keys and tags describe the current state of the unit, and will change regularly as gameplay progresses:
 +
* '''x''', '''y''': the location of the unit. By default (unless modified by [[#placement|'''placement''']] below) if a location isn't provided and the side the unit will belong to has a recall list, the unit will be created on the recall list. The recall list can also be explicitly specified as the location with "recall,recall".
  
 
* '''facing''': which way the unit is facing (this only affects how the unit is displayed).
 
* '''facing''': which way the unit is facing (this only affects how the unit is displayed).
** Possible values are '''se''', '''s''', '''sw''', '''nw''', '''n''', '''ne'''. Using '''sw''' is preferred for a "reversed" facing (looking to the left) and '''se''' for a normal (looking to the right) facing.
+
** Possible values are '''se''', '''s''', '''sw''', '''nw''', '''n''', '''ne'''. Note that some unit types may not have distinct animations for each direction.
  
* '''profile''': sets a portrait image for this unit. If the unit type already has a portrait set, this is used instead for this unit. When the unit advances, if the value of profile is different from the unit-type portrait, that value is preserved. If the profile field is empty or the same as the unit-type portrait, the level-advance changes the unit portrait to the default for the new level and type. See [[UnitTypeWML]] for the rules used for locating files.
+
* '''goto_x''':, '''goto_y''': the unit's current movement destination. Default is 0,0 i.e. the unit is not on a course.
** "unit_image" if 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).
 
  
* '''small_profile''': sets a small portrait image for this unit. See the '''profile''' attribute above for advancement and special values. As with [[UnitTypeWML]], the location heuristic of the '''profile''' attribute is disabled when the '''small_profile''' attribute is provided.
+
* '''hitpoints''': the HP of the unit. Default [[#max_hitpoints|'''max_hitpoints''']].
  
* '''max_attacks''': Default is 1. The number of attacks the unit can have per turn.
+
* '''experience''': the XP of the unit. Default is 0.
 
 
* '''max_experience''': The experience the unit needs to advance. If left out, this information will be taken from the unit's file.
 
  
* '''max_hitpoints''': The maximum hitpoints the unit has. If left out, this information will be taken from the unit's file.
+
* '''moves''': number of movement points the unit has left. Default is [[#max_moves|'''max_moves''']].
 +
: '''Note:''' Do not assume that moves=max_moves on turns when the unit doesn't move. The wesnoth AIs sometimes manipulate the moves variable during its turn, for internal reasons.
  
* '''max_moves''': The maximum moves the unit has. If left out, this information will be taken from the unit's file.
+
* '''resting''': whether the unit has not moved yet this turn. Used to decide whether to give the unit rest healing. Note that this can be true even if moves is not equal to max_moves.
  
* '''animate''': if ''yes'', fades the unit in like when it's recruited/recalled.
+
* '''attacks_left''': number of attacks the unit has left. Default is '''max_attacks'''.
  
 
* '''[status]''' the status of the unit. This affects different features of the unit, for example whether the unit loses health each turn. Default for all keys is 'no', but this can be changed by the scenario or by special abilities (see [[AbilitiesWML]]). The Status Table displays the status of each unit using the three images '''misc/poisoned.png''', '''misc/slowed.png''' and '''misc/petrified.png'''; other keys do not appear in the Status Table.
 
* '''[status]''' the status of the unit. This affects different features of the unit, for example whether the unit loses health each turn. Default for all keys is 'no', but this can be changed by the scenario or by special abilities (see [[AbilitiesWML]]). The Status Table displays the status of each unit using the three images '''misc/poisoned.png''', '''misc/slowed.png''' and '''misc/petrified.png'''; other keys do not appear in the Status Table.
 
** '''poisoned''': if 'yes', the unit loses 8 HP each turn. See also ''heals'', ''cures'', [[AbilitiesWML]].
 
** '''poisoned''': if 'yes', the unit loses 8 HP each turn. See also ''heals'', ''cures'', [[AbilitiesWML]].
** '''slowed''': if 'yes', the unit has 50% of its normal movement and does half damage. When the controller of the unit's turn is over, ''slowed'' is set to 'no'.  
+
** '''slowed''': if 'yes', the unit has 50% of its normal movement and does half damage. When the controller of the unit's turn is over, '''slowed''' is set to 'no'.  
 
** '''petrified''': if 'yes', the unit cannot move, attack, or be attacked.
 
** '''petrified''': if 'yes', the unit cannot move, attack, or be attacked.
 
** '''uncovered''': if 'yes', the unit has performed an action (e.g. attacking) that causes it to no longer be hidden until the next turn.
 
** '''uncovered''': if 'yes', the unit has performed an action (e.g. attacking) that causes it to no longer be hidden until the next turn.
Line 115: Line 114:
 
** '''unhealable''': if set to 'yes', the unit cannot be healed.
 
** '''unhealable''': if set to 'yes', the unit cannot be healed.
 
** {{DevFeature1.13|6}} '''invulnerable''': if 'yes', attacks can't hit the unit.
 
** {{DevFeature1.13|6}} '''invulnerable''': if 'yes', attacks can't hit the unit.
** One can add other keys to [status], but they must have boolean values. For example, a scenario can set unit.status.''my_custom_key'' to 'yes' or 'no'.
+
** One can add other keys to [status], but they must have boolean values, and they will not do anything meaningful on their own (but can be checked from events and acted upon accordingly). For example, a scenario can set unit.status.''my_custom_key'' to 'yes' or 'no'.
  
* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).
+
* {{DevFeature1.13|6}} '''invulnerable''': a shorthand to set the ''invulnerable'' status.
 +
 
 +
== Creation Options ==
 +
In addition to the unit's persistent data itself, there are several options for controlling how the unit will be created, as follows:
 +
* <span id="placement">'''placement'''</span>: How the unit should be placed: can be one value or a comma-separated list of values. Default value is 'map,leader' for a leader given directly in [side], "" otherwise. By default, 'map,recall' is implicitly appended to the end of the list.
 +
** '''map''': If x,y are explicitly given and point to a valid on-map location - try to place the unit at the nearest free location to there, never overwriting existing units. Successful if x,y are given and a valid on-map vacant location near it can be found.
 +
** '''leader''': Try to place unit near the leader, if leader is not present or is in recall list - try to place unit near the start location for this side. Successful if a valid on-map vacant location can be found near leader or near start location.
 +
** '''recall''': Place unit on recall list. Always successful.
 +
** '''map_overwrite''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location, if there was a unit there - overwriting it, without firing events.
 +
** '''map_passable''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location; if the hex is of an impassable terrain for the unit being placed, or is already occupied by another unit, the new unit will be placed in the nearest vacant hex.
 +
** '''leader_passable''': Similar to "leader", with the additional restriction that the selected location is not impassable for the unit being placed.
  
* '''[modifications]''' changes that have been made to the unit.
+
* '''to_variable''': creates the unit into the given variable instead of placing it on the map.
** '''[trait]''' a trait the unit has. Same format as [trait], [[UnitsWML]].
 
** '''[object]''' an object the unit has. Same format as [object], [[DirectActionsWML]].
 
** '''[advance]''' an advancement the unit has. Same format as [advancement], [[UnitTypeWML]]. Might be used if the unit type has some advancements, but this particular one is supposed to have some of them already taken. {{DevFeature1.13|2}} In 1.13.2 and later this has been renamed to [advancement], to match the UnitTypeWML tag of the same name.
 
  
* '''[filter_recall]''' A leader can only recall those units which pass the SUF.
+
* '''generate_name''': (default=yes) will generate a new '''name''' if there isn't one specified for the unit, as if the unit were a freshly-recruited one.
**'''[[StandardUnitFilter]]''' tags and keys
 
  
* '''unit_description''': overrides the unit type description for this unit. You will probably want to set up a ''post_advance'' [[EventWML|event]] to override the default description after promotions. Or better, use an object with a profile [[EffectWML|effect(s)]] to filter on unit type and change the unit description and/or portrait.
+
* '''random_traits''': "no" will prevent random trait generation for units. You should only need to set this for placed nonleaders in multiplayer games or if you want to give the unit fewer traits than it would normally get for its unit type. When generating traits for a unit, first traits the unit has already been given are excluded. Then "musthave" traits (undead, mechanical) for the unit type are given. Then for leaders ('''canrecruit=yes''') traits that are not available to "any" (currently that's all of them to avoid a multiplayer OOS issue, but later will be restricted based on multiplayer play balance issues) are removed from consideration. Then traits are added randomly until the maximum allowed for the unit type is reached or there are no more available traits. Random traits can now be used in MP games but only when spawned in an event, so not for leaders and other units in the [side] definition.
  
* '''[event]''' The event is copied from this unit's wml description into the scenario. The event is carried along with the unit (it can advance etc) and inserted into every scenario where this unit is first created. A [unit][event] requires a non-empty id= attribute.
+
* <span id="random_gender">'''random_gender'''</span>: "yes" will cause the gender of the unit with male and female variations to be male 50% of the time, female 50% of the time. If the unit has only one gender variant it will always be given the correct one.
  
* '''[ai]''' This affects how the computer will control this unit (currently only used by [[FormulaAI]]).
+
* '''animate''': if ''yes'', fades the unit in like when it's recruited/recalled.
** '''formula''': if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side
 
** '''priority''', '''loop_formula''', '''[vars]''': see the [[FormulaAI]] documentation for details
 
  
 
== See Also ==
 
== See Also ==

Revision as of 18:43, 29 October 2016

[edit]WML Tags

A:

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;

B:

base_unit, berserk, binary_path, break, brush;

C:

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;

D:

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;

E:

editor_group, editor_music, editor_times, effect, else (action, animation), elseif, endlevel, end_turn (action, replay), enemy_of, engine, entry, era, event, 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_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, for, foreach, frame, full_heal;

G:

game_config, get_global_variable, goal, gold, gold_carryover;

H:

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;

I:

idle_anim, if (action, animation), illuminates, image, 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, portrait, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, 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_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resource, return, role, rule;

S:

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;

T:

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;

U:

unhide_unit, unit, 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] tag describes a single unit on the map or in memory, for example Konrad. It is different from the [unit_type] in [units], which describes a class of units. However it takes many of the same keys and thus can generally override the inherited properties from the associated [unit_type].

[unit] can be used inside [side] (SideWML) for units present at start of the scenario, or as DirectActionsWML for units created during the game. (It is also used in save-files.)

Unit Data

The following keys and tags describe the unit itself, and will persist with the unit (though some may change automatically when the unit advances):

  • type: the ID of the unit's unit type. This key is mandatory. See UnitTypeWML.
  • variation: the [variation] of the [unit_type] as which the unit will appear.
  • parent_type: overrides type if this is present. This is likely of little use to WML authors; it is automatically generated when needed by the game (to keep track of some [unit_type][variation]s).
  • side: the side that the unit is on. It has to be an existing side, even if the unit is created in a variable. Mandatory except when the [unit] tag appears inside a [side], in which case it defaults to that side.
  • id: a unique identifier for the unit. This is (usually) not displayed to the player, but is to be used only for identifying and filtering units. If not specified, a random one will be generated for the unit to ensure that each unit has a unique id attribute (as will happen when a unit is recruited normally). In older versions, the description attribute specified a unique ID. (The one instance when an id is displayed to the player is when the leader's id is used as the default for a side's current_player attribute.) Note: While it IS technically possible to create multiple units with the same ID, doing so may produce unpredictable results in many cases. WML should therefore be structured in such a way that no two units in existence ever end up with the same ID.
  • gender: can be set to male or female to designate the gender of the unit. Default is male (unless random_gender is set to "yes"), but if the unit has only a female variant it will be female.
  • name: the user-visible name of the unit. Note that the player may use the "rename unit" action to change this (unless unrenamable is also set).
  • unrenamable: if 'yes', the user-visible name of the unit cannot be changed by the player (which is only possible when the unit is on the player's side anyway).
  • canrecruit: a special key for leaders.
    • no: default. Unit cannot recruit.
    • yes: unit can recruit.
Normally when a team controls no units with canrecruit=yes, that team loses. However, even if your team has lost you continue to play with whatever units you still have until the scenario is over. Usually scenarios end when only one team is left with a leader that can recruit, but special victory conditions can be set up in campaigns. Normally you want to set the leader of a side with canrecruit=yes. If you don't want the leader to recruit, it is usually better to just not give him any unit types to recruit, than to make a special victory condition. Units with canrecruit=yes are exempt from upkeep costs. So that leaders do not need to be given the loyal trait.
More than one unit with canrecruit=yes for the same side (see SideWML) are allowed in single player, if the side is human-controlled.
  • extra_recruit: a list of unit types which this unit can recruit in addition to the ones given by its [side]recruit= (only relevant for units with canrecruit=yes).
  • [filter_recall] A leader can only recall those units which pass the SUF. (Meaningful only if canrecruit=yes.)
  • upkeep: the amount of upkeep the unit will require each turn.
    • loyal: no upkeep cost. Can be changed by the effect 'loyal' (see EffectWML)
    • free: synonymous with "loyal".
    • full: unit costs level upkeep (see UnitTypeWML).
    • An integer can be used to set the upkeep cost to that number.
    • The default is "full".
    • Leaders (units with canrecruit=yes) never pay upkeep no matter what upkeep is set to.
    • Normally you don't want to muck with this value. If you want to give a side units without upkeep costs, give those units the 'loyal' trait.
  • overlays: a comma-separated list of images that are overlayed on the unit.
  • max_hitpoints: The maximum hitpoints the unit has when at full health. Default is the max HP set for the [unit_type] described by type.
  • max_experience: The experience the unit needs to advance. Default is the experience required for the [unit_type] described by type.
  • max_moves: The maximum number of movement points the unit has. Default is the number of movement specified for the [unit_type] described by type.
  • max_attacks: The number of attacks the unit can have per turn. Default is the number of attacks specified for the [unit_type] described by type.
  • profile: sets a portrait image for this unit. Default is the portrait image set for the [unit_type] described by type. When the unit advances, if the value of profile is different from the unit-type portrait, that value is preserved. If the profile field is empty or the same as the unit-type portrait, the level-advance changes the unit portrait to the default for the new level and type. See UnitTypeWML for the rules used for locating files.
    • 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).
  • small_profile: sets a small portrait image for this unit. See the profile attribute above for advancement and special values. As with UnitTypeWML, the location heuristic of the profile attribute is disabled when the small_profile attribute is provided.
  • [variables] a set of variables that will be stored when this unit is stored (See [store_unit], InternalActionsWML). The attribute variable=value means that when the unit is stored in the array unit, the variable unit.variables.variable will have the value value (See VariablesWML).
  • [modifications] changes that have been made to the unit.
    • [trait] a trait the unit has. Same format as [[UnitsWML#[trait]|[trait], UnitsWML]].
    • [object] an object the unit has. Same format as [[DirectActionsWML#[object]|[object], DirectActionsWML]].
    • [advance] an advancement that has already been applied to the unit. Same format as AMLA [advancement], UnitTypeWML. These are automatically added as the unit has AMLA advancements applied to it, but can also be specified manually to indicate that the unit already has a particular advancement applied, or to disable certain advancements (by ID). (Version 1.13.2 and later only) In 1.13.2 and later this has been renamed to [advancement], to match the UnitTypeWML tag of the same name.
  • [event] The event is copied from this unit's WML description into the scenario. The event is carried along with the unit (even during advancement) and inserted into a scenario whenever this unit is first included. A [unit][event] requires a non-empty id= attribute.
  • unit_description: overrides the unit type description for this unit. Note that this will be reset when the unit advances. To avoid this, one can either set up a post_advance event to override the default description after promotion, or use an [object] with a profile effect to change the unit description.
  • hp_bar_scaling: Overrides the attribute in GameConfigWML (and the [unit_type], if present).
  • xp_bar_scaling: Overrides the attribute in GameConfigWML (and the [unit_type], if present).
  • ai_special: causes the unit to act differently
    • "guardian" the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). Does the same as [status] guardian = 'yes'.
  • [ai] This affects how the computer will control this unit (currently only used by FormulaAI).
    • formula: if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side
    • priority, loop_formula, [vars]: see the FormulaAI documentation for details
  • traits_description: the description of the unit's traits which is displayed. However if it is not specified explicitly, the unit's actual traits' names will be used instead, so it is normally not necessary to set this.

Unit State

The following keys and tags describe the current state of the unit, and will change regularly as gameplay progresses:

  • x, y: the location of the unit. By default (unless modified by placement below) if a location isn't provided and the side the unit will belong to has a recall list, the unit will be created on the recall list. The recall list can also be explicitly specified as the location with "recall,recall".
  • facing: which way the unit is facing (this only affects how the unit is displayed).
    • Possible values are se, s, sw, nw, n, ne. Note that some unit types may not have distinct animations for each direction.
  • goto_x:, goto_y: the unit's current movement destination. Default is 0,0 i.e. the unit is not on a course.
  • experience: the XP of the unit. Default is 0.
  • moves: number of movement points the unit has left. Default is max_moves.
Note: Do not assume that moves=max_moves on turns when the unit doesn't move. The wesnoth AIs sometimes manipulate the moves variable during its turn, for internal reasons.
  • resting: whether the unit has not moved yet this turn. Used to decide whether to give the unit rest healing. Note that this can be true even if moves is not equal to max_moves.
  • attacks_left: number of attacks the unit has left. Default is max_attacks.
  • [status] the status of the unit. This affects different features of the unit, for example whether the unit loses health each turn. Default for all keys is 'no', but this can be changed by the scenario or by special abilities (see AbilitiesWML). The Status Table displays the status of each unit using the three images misc/poisoned.png, misc/slowed.png and misc/petrified.png; other keys do not appear in the Status Table.
    • poisoned: if 'yes', the unit loses 8 HP each turn. See also heals, cures, AbilitiesWML.
    • slowed: if 'yes', the unit has 50% of its normal movement and does half damage. When the controller of the unit's turn is over, slowed is set to 'no'.
    • petrified: if 'yes', the unit cannot move, attack, or be attacked.
    • uncovered: if 'yes', the unit has performed an action (e.g. attacking) that causes it to no longer be hidden until the next turn.
    • guardian: if 'yes', the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). Does the same as ai_special = "guardian".
    • unhealable: if set to 'yes', the unit cannot be healed.
    • (Version 1.13.6 and later only) invulnerable: if 'yes', attacks can't hit the unit.
    • One can add other keys to [status], but they must have boolean values, and they will not do anything meaningful on their own (but can be checked from events and acted upon accordingly). For example, a scenario can set unit.status.my_custom_key to 'yes' or 'no'.

Creation Options

In addition to the unit's persistent data itself, there are several options for controlling how the unit will be created, as follows:

  • placement: How the unit should be placed: can be one value or a comma-separated list of values. Default value is 'map,leader' for a leader given directly in [side], "" otherwise. By default, 'map,recall' is implicitly appended to the end of the list.
    • map: If x,y are explicitly given and point to a valid on-map location - try to place the unit at the nearest free location to there, never overwriting existing units. Successful if x,y are given and a valid on-map vacant location near it can be found.
    • leader: Try to place unit near the leader, if leader is not present or is in recall list - try to place unit near the start location for this side. Successful if a valid on-map vacant location can be found near leader or near start location.
    • recall: Place unit on recall list. Always successful.
    • map_overwrite: If x,y are explicitly given and point to a valid on-map location - try to place unit at this location, if there was a unit there - overwriting it, without firing events.
    • map_passable: If x,y are explicitly given and point to a valid on-map location - try to place unit at this location; if the hex is of an impassable terrain for the unit being placed, or is already occupied by another unit, the new unit will be placed in the nearest vacant hex.
    • leader_passable: Similar to "leader", with the additional restriction that the selected location is not impassable for the unit being placed.
  • to_variable: creates the unit into the given variable instead of placing it on the map.
  • generate_name: (default=yes) will generate a new name if there isn't one specified for the unit, as if the unit were a freshly-recruited one.
  • random_traits: "no" will prevent random trait generation for units. You should only need to set this for placed nonleaders in multiplayer games or if you want to give the unit fewer traits than it would normally get for its unit type. When generating traits for a unit, first traits the unit has already been given are excluded. Then "musthave" traits (undead, mechanical) for the unit type are given. Then for leaders (canrecruit=yes) traits that are not available to "any" (currently that's all of them to avoid a multiplayer OOS issue, but later will be restricted based on multiplayer play balance issues) are removed from consideration. Then traits are added randomly until the maximum allowed for the unit type is reached or there are no more available traits. Random traits can now be used in MP games but only when spawned in an event, so not for leaders and other units in the [side] definition.
  • random_gender: "yes" will cause the gender of the unit with male and female variations to be male 50% of the time, female 50% of the time. If the unit has only one gender variant it will always be given the correct one.
  • animate: if yes, fades the unit in like when it's recruited/recalled.

See Also