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 used in standard unit filter (FilterWML). Note that this field is not filled in with names created at random when recruiting units. Nor is it affected by a player renaming a unit. So when designing maps you don't have to worry about naming conflicts.
- user_description the name of the unit that is shown to the user. Default description.
- generate_description if set to "yes", will generate a new name (user_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 Template:DevFeature choose the traits randomly, just like a recruited unit. Don't use this in a MP Scenario, this can cause OOS.
- 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.
- upkeep the amount of upkeep the unit costs.
- 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).
- "normal" (default) unit is facing to the right.
- "reverse" unit is facing to the left.
- profile Template:DevFeature sets a default portrait image for this unit. If the unit type already has a portrait set, this is used instead for this unit.
- "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).
- [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 -1 strike on each attack with strikes>1. When the controller of the unit's turn is over, slowed is set to 'off' Template:DevFeature slow now halves damage instead of removing one strike
- stone if 'on', the unit cannot move, attack, or be attacked.
- ambush if 'on', 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.