SingleUnitWML

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

This contains keys and tags which describe the unit's persistent data, as well as certain state variables which will also persist with the unit but will change frequently as gameplay progresses. Finally, there are some keys to set certain one-time options for how the unit will be initially created, which will not persist beyond initial creation.

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.

language_name: the name of the unit's unit type. 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. Defaults to 1, except when the [unit] tag appears inside a [side], in which case the unit always belongs to that side, and this key is ignored.

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). Although this is a translated string, see proper nouns in strings before using it in a translatable string.

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.)
- StandardUnitFilter tags and keys

level: the unit's current level. Defaults to the level of the [unit_type] described by type. This is generally not set manually.

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.

(Version 1.13.0 and later only) recall_cost: the recall cost of this unit. Overrides the values specified by the unit's type ([unit_type]), its side ([side]), and the global [game_config] value. 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.

overlays: a comma-separated list of images that are overlayed on the unit.
- (Version 1.15.0 and later only) This key is supported when creating a unit from WML, but will be empty when writing the unit back to WML; the overlays will instead be stored as [modifications].

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.

vision: The the number of vision points to calculate the unit's sight range. Default is the number of vision points specified for the [unit_type] described by type.

jamming: (Version 1.15.0 and later only) The number of jamming points for the unit. Default is the number of jamming points specified for the [unit_type] described by type.

flying: 'yes' if the unit's movetype has flying=yes. For units that don't fly, the flying attribute is generally omitted rather than being recorded as 'no'. In SingleUnitWML, this attribute has been called flying since it was added in 1.11.2, it was never called 'flies'.

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).
- If "none" is given instead of a filename, no image will be displayed.

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.

role: used in standard unit filter (FilterWML). Can be set using [role] (see InternalActionsWML).

[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). The subnode mods is special as it is deleted on every unit rebuild (for example when the unit advances or when an [object] is removed). This makes it possible to implement [effect]s that change variables, as those will also be reapplied whenever the unit is reset. (so in particular if your effect changes the variables mods.<whatever> [remove_object] will work properly for those objects.) For example the following code will define a apply_to=moves_on_recruits effect that gives units with that effect full movement when recruited

function wesnoth.effects.move_on_recruit(u, cfg)
	-- maybe better use a status than a variable ?
	u.variables["mods.move_on_recruit"] = true
end
on_event("recruit,recall", function(ec)
	local unit = wesnoth.get_unit(ec.x1, ec.y1)
	if unit and unit.variables["mods.move_on_recruit"] then
		unit.attacks_left = 1
		unit.moves = unit.max_moves
	end
end)

And since we used the mods subtable, [remove_object] will work properly for objects that give this effect.

[modifications]: changes that have been made to the unit.
- [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 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.

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.

[special_note] (Version 1.15.2 and later only) see UnitTypeWML#Special_Notes.

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
- (Version 1.15.? and later only) [candidate_action]: Add a candidate action that only applies to this unit; see here for details. The [filter_own] tag is not supported.
  - stage: If specified, the candidate action is added to the stage with the given ID, instead of the default stage (which is main_loop).
- (Version 1.15.? and later only) [micro_ai]: Add a micro AI that only applies to this unit; see Micro AIs for details. This tag does not support side, action, or [filter].

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.

alignment: one of lawful/neutral/chaotic/liminal (See TimeWML). Default is the alignment of the [unit_type] described by type. This is generally not set manually.

advances_to: comma-separated list of unit types to which this unit can advance. Will override the default provided by the [unit_type]. This is generally not set manually.

race: See [race]. Will override the default provided by the [unit_type]. This is generally not set manually.

undead_variation: Will override the default provided by the [unit_type]. This is generally not set manually.

usage: Will override the default provided by the [unit_type]. This is generally not set manually.

zoc: whether the unit has a zone of control. Will override the default provided by the [unit_type]. This is generally not set manually.

[movement_costs], [vision_costs], [defense], and [resistance]: Can be used to modify existing values.

[attack]: Takes the same syntax as [unit_type][attack]. By default, the attacks from the [unit_type] will be included. Note: using this tag will replace all [attack] tags with the new one.

hidden: Implementation detail of [hide_unit]. This should not be set manually.

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

location_id: (Version 1.13.8 and later only) the location of the unit, referencing one of the special locations defined by the map. This overrides x and y if present but otherwise has the same effect and can be modified by the placement options.

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.

hitpoints: the HP of the unit. Default max_hitpoints.

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. For cutscenes, it may be useful to set this manually.
- 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 through normal game mechanics. This includes the healing by resting. It does not prevent the unit from being healed by WML or Lua code.
- unpoisonable: if set to 'yes', the unit cannot be poisoned.
- undrainable: if set to 'yes', the attacker can't gain health with drain ability attacking this unit.
- unplagueable: if set to 'yes', the unit cannot be affected by plague attack.
- not_living: Deprecated, this is automatically set when all three above are set and vice versa.
- unslowable: if set to 'yes', the unit cannot be slowed.
- unpetrifiable: if set to 'yes', the unit cannot be petrified.
- invulnerable: (Version 1.13.6 and later only) if 'yes', attacks can't hit the unit. The AI and the attack dialog take it into account.
- 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'.

invulnerable: (Version 1.13.6 and later only) a shorthand to set the invulnerable status. Useful in CommandMode for debugging purposes. It's recommended to use [status] in written code instead.

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 (or location_id) 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 (or location_id) 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. (Version 1.13.8 and later only) Deprecated, use placement=map and overwrite=yes instead.
- 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. (Version 1.13.8 and later only) Deprecated, use placement=map and passable=yes instead.
- leader_passable: Similar to "leader", with the additional restriction that the selected location is not impassable for the unit being placed. (Version 1.13.8 and later only) Deprecated, use placement=leader and passable=yes instead.
passable: (Version 1.13.8 and later only) (default=no) If yes, and the specified location is of an impassable terrain for the unit being placed, the new unit will be placed in the nearest hex that is of a passable terrain for it.
overwrite: (Version 1.13.8 and later only) (default=no) If yes, always place the unit at the exact specified location, overwriting the existing unit if there is one. Generally you don't want to use this together with placement=leader.

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.

to_variable: (only for [event][unit]) creates the unit into the given variable instead of placing it on the map.

animate: whether to display the recruitment animation for this unit as if it were being recruited/recalled. Defaults to "no". Irrelevant when the [unit] tag appears inside a [side].

SingleUnitWML

Contents

Unit Data

Unit State

Creation Options

See Also