Difference between revisions of "SingleUnitWML"

From The Battle for Wesnoth Wiki
(How to describe a single unit: added info about how random_traits can be used in MP)
(Unit Data)
 
(135 intermediate revisions by 43 users not shown)
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.
 +
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]'''.
  
This tag, '''[unit]''', describes a single unit on the map, for example Konrad.
+
'''[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.)
It is different from the [unit] in [units], which describes a class of units.
 
  
The following keys are recognized:
+
This contains keys and tags which describe the unit's [[#Unit Data|persistent data]], as well as certain [[#Unit State|state variables]] which will also persist with the unit but will change frequently as gameplay progresses. Finally, there are some keys to set certain [[#Creation Options|one-time options]] for how the unit will be initially created, which will ''not'' persist beyond initial creation.
* ''type'' the ID of the unit's unit type. See [[UnitWML]].
 
  
* ''side'' the side that the unit is on.
+
== 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):
 +
* {{anchor|type|'''type'''}}: the ID of the unit's unit type. This key is mandatory. See [[UnitTypeWML]].
  
* ''gender'' can be set to male or female to designate the gender of the unit. Default is male.
+
* {{anchor|language_name|'''language_name'''}}: the name of the unit's unit type. See [[UnitTypeWML]].
  
* ''x'', ''y'' the location of the unit. 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.
+
* '''variation''': the [variation] of the [unit_type] as which the unit will appear.
  
* ''description'' a unique identifier for the unit. This is not displayed to the player, but is to be used only for identifying and filtering for units. {{DevFeature}} 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 ''description''.
+
* '''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).
  
* ''user_description'' the name of the unit that is shown to the player. Note that the player may use the "rename unit" action to change this.
+
* '''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.
  
* ''generate_description'' if set to "yes", will generate a new name (''user_description'' only, not ''description'') for the unit, as if the unit was a freshly-recruited one.
+
* '''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.
  
* ''unrenamable'' if 'yes', the ''user_description'' cannot be changed by the player (which is only possible when the unit is on the player's side anyway).
+
* '''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.
  
* ''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.
+
* '''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 [[GettextForWesnothDevelopers#Proper_nouns_in_strings|proper nouns in strings]] before using it in a translatable string.
  
* ''random_traits'' {{DevFeature}}"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=1''') 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.
+
* <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.
** '0' default. Unit cannot recruit.
+
** '''no''': default. Unit cannot recruit.
** '1' unit can recruit.
+
** '''yes''': unit can recruit.
: Normally when a team controls no units with '''canrecruit=1''', 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=1'''. 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. {{DevFeature}} Units with '''canrecruit=1''' are exempt from upkeep costs. So that leaders do not need to be given the ''loyal'' trait.
+
: 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.
  
* ''variation'' the variation of itself the unit should be created as.
+
* '''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''').
  
* ''upkeep'' the amount of upkeep the unit costs.
+
* {{anchor|filter_recall|'''[filter_recall]'''}}: A leader can only recall those units which pass the SUF. (Meaningful only if canrecruit=yes.)
** "loyal" no upkeep cost. Can be changed by the effect 'loyal' (see [[EffectWML]])
+
**'''[[StandardUnitFilter]]''' tags and keys
** "full" unit costs ''level'' upkeep (see [[UnitWML]]).
+
 
 +
* '''level''': the unit's current level. Defaults to the level of the [unit_type] described by [[#type|'''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.
 
** An integer can be used to set the upkeep cost to that number.
 
** The default is "full".
 
** The default is "full".
** Leaders (units with '''canrecruit=1''') never pay upkeep no matter what upkeep is set to.
+
** 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.
 
** 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 list of images that are overlayed on the unit.
+
* {{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.15|0}} 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.
  
* ''goto_x'', ''goto_y'' UI settings that control courses. Default is 0,0 i.e. the unit is not on a course.
+
* '''overlays''': a comma-separated list of images that are overlayed on the unit.
 +
** {{DevFeature1.15|0}} 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].
  
* ''hitpoints'' the HP of the unit. Default is the max HP for ''type''.
+
* <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''']].
  
* ''experience'' the XP of the unit. Default is 0.
+
* '''max_experience''': The experience the unit needs to advance. Default is the experience required for the [unit_type] described by [[#type|'''type''']].
  
* ''moves'' number of move points the unit has left. Default is the movement for ''type''.
+
* {{anchor|max_moves|'''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|'''type''']].
  
* ''resting'' whether the unit has not moved yet this turn. Used to decide whether to give a unit rest healing.
+
* '''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|'''type''']].
  
* ''role'' used in standard unit filter ([[FilterWML]]). Can be set using [role] (see [[InternalActionsWML]]).
+
* '''jamming''': {{DevFeature1.15|0}} The number of jamming points for the unit. Default is the number of jamming points specified for the [unit_type] described by [[#type|'''type''']].
  
* ''ai_special'' causes the unit to act differently.
+
* '''flying''': 'yes' if the unit's [[UnitsWML#.5Bmovetype.5D|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'.
** "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).
 
  
* ''facing'' which way the unit is facing (this only affects how the unit is displayed).
+
* {{anchor|max_attacks|'''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|'''type''']].
** 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.
 
  
* ''profile'' sets a default 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.
+
* '''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).
 +
** If "none" is given instead of a filename, no image will be displayed.
  
** "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.
  
* ''animate'' if ''yes'', fades the unit in like when it's recruited/recalled.
+
* '''role''': used in standard unit filter ([[FilterWML]]). Can be set using [role] (see [[InternalActionsWML]]).
  
* '''[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 'off', but this can be changed by the scenario or by special abilities (see [[AbilitiesWML]]). The status of a unit is displayed on the Status Table; each status modification ''statusmod'' is represented by the image '''misc/statusmod.png'''.
+
* {{anchor|variables|'''[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
** ''poisoned'' if 'on', the unit loses 8 HP each turn. See also ''heals'', ''cures'', [[AbilitiesWML]].
 
** ''slowed'' if 'on', 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 'off' 
 
** ''stone'' if 'on', the unit cannot move, attack, or be attacked.
 
** ''hides'' if 'yes', the unit cannot be seen by opponents.
 
  
* '''[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]]).
+
<syntaxhighlight lang='lua'>
 +
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)
 +
</syntaxhighlight>
 +
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.
+
* {{anchor|modifications|'''[modifications]'''}}: changes that have been made to the unit.
** '''[trait]''' a trait the unit has. Same format as [trait], [[UnitsWML]].
+
** '''[trait]''' a trait the unit has. Same format as [[UnitsWML#.5Btrait.5D|[trait], UnitsWML]].
** '''[object]''' an object the unit has. Same format as [object], [[DirectActionsWML]].
+
** '''[object]''' an object the unit has. Same format as [[DirectActionsWML#.5Bobject.5D|[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.
  
* ''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 {{DevFeature}}.
+
* '''[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'' [[EventWML|event]] to override the default description after promotion, or use an [object] with a profile [[EffectWML|effect]] to change the unit description.
 +
 
 +
* '''[special_note]''' {{DevFeature1.15|2}} 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''''.
 +
 
 +
* {{anchor|ai|'''[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
 +
** {{DevFeature1.15|?}} '''[candidate_action]''': Add a candidate action that only applies to this unit; see [[Wesnoth_AI_Framework#The_.5Bcandidate_action.5D_Tag|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).
 +
** {{DevFeature1.15|?}} '''[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|'''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 {{tag|UnitsWML|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 [[UnitsWML#.5Bmovetype.5D|existing values]].
 +
 
 +
*'''[attack]''': Takes the same syntax as [[UnitTypeWML#Attacks|[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 [[InterfaceActionsWML#%5Bhide_unit%5D|[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|'''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''': {{DevFeature1.13|8}} 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|'''max_hitpoints''']].
 +
 
 +
* '''experience''': the XP of the unit. Default is 0.
 +
 
 +
* '''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.
 +
 
 +
* '''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'''.
 +
 
 +
* {{anchor|status|'''[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''': {{DevFeature1.13|6}} 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''': {{DevFeature1.13|6}} 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:
 +
* <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 (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. {{DevFeature1.13|8}} 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. {{DevFeature1.13|8}} 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. {{DevFeature1.13|8}} Deprecated, use placement=leader and passable=yes instead.
 +
* '''passable''': {{DevFeature1.13|8}} (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''': {{DevFeature1.13|8}} (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.
 +
 
 +
* <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.
 +
 
 +
* '''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].
  
 
== See Also ==
 
== See Also ==
  
* [[UnitWML]]
+
* [[UnitTypeWML]]
 +
* [[InternalActionsWMLUnitTags]]
 
* [[ReferenceWML]]
 
* [[ReferenceWML]]
 +
 +
[[Category:WML Reference]]

Latest revision as of 16:04, 25 July 2024

[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] 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.)
  • 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.
  • [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.
  • 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.
  • 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'.

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

See Also

This page was last edited on 25 July 2024, at 16:04.