From The Battle for Wesnoth Wiki
How to describe a single unit
This tag, [unit], describes a single unit on the map, for example Konrad. It is different from the [unit] in [units], which describes a class of units.
The following keys are recognized:
- type the ID of the unit's unit type. See UnitWML.
- side the side that the unit is on.
- gender can be set to male or female to designate the gender of the unit. Default is male.
- 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.
- 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. Template: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.
- 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.
- 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.
- 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).
- 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.
- random_traits 'yes' will choose the traits randomly, just like a recruited unit. Don't use this in an MP Scenario as this will cause an Out of Sync (OOS) error.
- canrecruit a special key for leaders.
- '0' default. Unit cannot recruit.
- '1' 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. Template:DevFeature Units with canrecruit=1 are exempt from upkeep costs. So that leaders do not need to be given the loyal trait.
- variation the variation of itself the unit should be created as.
- upkeep the amount of upkeep the unit costs.
- "loyal" no upkeep cost. Can be changed by the effect 'loyal' (see EffectWML)
- "full" unit costs level upkeep (see UnitWML).
- An integer can be used to set the upkeep cost to that number.
- The default is "full".
- Leaders (units with canrecruit=1) 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 list of images that are overlayed on the unit.
- goto_x, goto_y UI settings that control courses. Default is 0,0 i.e. the unit is not on a course.
- hitpoints the HP of the unit. Default is the max HP for type.
- experience the XP of the unit. Default is 0.
- moves number of move points the unit has left. Default is the movement for type.
- resting whether the unit has not moved yet this turn. Used to decide whether to give a unit rest healing.
- 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).
- 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.
- 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.
- "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).
- animate if yes, fades the unit in like when it's recruited/recalled.
- [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.
- 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).
- [modifications] changes that have been made to the unit.
- unit_description overrides the unit type description for this unit. You will probably want to set up a post_advance event to override the default description after promotions.