UnitTypeWML

From The Battle for Wesnoth Wiki
Revision as of 22:38, 7 January 2006 by Noyga (talk | contribs) (The [unit] tag)

The [unit] tag

Each [unit] tag defines one unit type.

Unit animation syntax is described in AnimationWML.

The following key/tags are recognized:

  • id the value of the type key for units of this type. An id should consist only of alphanumerics and underscores. type keys are found in SingleUnitWML and FilterWML.
  • name (translatable) displayed in the Status Table for units of this type.
  • race See [race], UnitsWML. Also used in standard unit filter (see FilterWML).
  • num_traits the number of traits that units of this type should receive when they are recruited, overriding the value set in the [race] tag.
  • gender has a value of either male or female, and determines which of the keys male_names and female_names should be read. When a unit of this type is recruited, it will be randomly assigned a name by the random name generator, which will use these names as a base.
  • ability a list of the unit's abilities. See AbilitiesWML for a description of abilities.
  • hitpoints the maximum HP that the unit has, and the HP it has when it is created.
  • movement the number of move points that this unit recieves each turn.
  • experience, advanceto When this unit has experience greater than or equal to experience, it is replaced by a unit with 0 experience of the type that the value of advanceto refers to. All modifications that have been done to the unit are applied to the unit it is replaced by.
  • [advancefrom] allows a campaign-specific unit to be spliced into an already existing advancement tree. It should generally be used only inside a campaign ifdef, to prevent changes to other campaigns. This tag makes changes to the advanceto and experience keys of a base unit to make it advance into this unit. It takes these keys:
    • unit the id of the base unit from which this unit advances. This adds the unit into the list of units which unit can advance into.
    • experience is optional. If present and lower than the experience already required for the base unit to advance, then the experience to advance is lowered. Note: this will also lower the experience required to advance to other units which the base unit can advance into.
  • cost when a player recruits a unit of this type, the player loses cost gold. If this would cause gold to drop below 0, the unit cannot be recruited.
  • level the amount of upkeep the unit costs. After this unit fights, its opponent gains level experience. See also kill_experience (GameConfigWML), and leadership (AbilitiesWML).
  • alignment how the unit's damage should be affected by its lawful bonus (See TimeWML).
  • usage the way that the AI should recruit this unit, as determined by the scenario designer. (See recruitment_pattern, AiWML). The following are conventions on usage:
    • 'scout' Fast,
    • 'fighter' Melee fighter,
    • 'archer' Ranged fighter,
    • 'mixed fighter' Melee and ranged fighter, and
    • 'healer' Specialty 'heals' or 'cures'.
  • unit_description (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
  • movetype See [movetype], UnitsWML.

Note that the tags [movement_costs], [defense], and [resistance] can be used to modify this movetype. After max level advancement support is not used in standard Wesnoth, but you can add this tag into standard Wesnoth units:

  • [advancement] describes what happens to a unit when it reaches the XP required for advancement. It is considered as an advancement in the same way as advancement described by advanceto; however, if the player chooses this advancement, the unit will have one or more effects applied to it instead of advancing.
    • id normal internationalization id.
    • description a description (see DescriptionWML) displayed as the option for this advancement if there is another advancement option that the player must choose from; otherwise, the advancement is chosen automatically and this key is irrelevant.
    • max_times default 1. The maximum times the unit can be awarded this advancement.
    • [effect] A modification applied to the unit whenever this advancement is chosen. See EffectWML
  • [attack] one of the unit's attacks.
    • description a translatable text for name of the attack, to be displayed to the user.
    • name the name of the attack. Used as a default description, if description is not present, and to determine the default icon, if icon is not present (if name=x then icon=attacks/x.png is assumed unless present). Non-translatable. Used for the has_weapon key; see FilterWML
    • type the damage type of the attack. Used in determining resistance to this attack (see [resistances], UnitWML). Possible values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'holy'.
    • special the special ability of the attack. Currently having more than 1 ability is not supported. See AbilitiesWML for a list of possible values.
    • icon the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory.
    • range the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. Also displayed on the status table in parentheses; 'short'(default) displays "melee", while 'long' displays "ranged". 1.1.x: range can be anything, standard values are now "melee" and "ranged". short and long will be treated as totally different ranges, this value should be made translatable.
    • damage the damage of this attack
    • number the number of strikes per attack this weapon has
    • attack_weight helps the AI to choose which attack to use when attacking; highly weighted attacks are more likely to be used. Setting it to 0 disables the attack on attack (version > 1.1)
    • defense_weight used to determine which attack is used for retaliation. This affects gameplay, as the player is not allowed to determine his unit's retaliation weapon. Setting it to 0 disable the attacks on defense (version > 1.1)

For those two settings, the engine usually chooses the attack with the best average total damages * weight (default weight = 1.0).

    • [animation]
This describes an animation for this attack. If multiple animations are present, one will be randomly chosen each time the unit attacks. See AnimationWML for possible keys.
  • [variation] Defines a variation of a unit.
    • variation_name The name of the variation.
All other keys in [variation] are the same as for [unit] itself. TODO: What is a variation good for?
  • [male], [female] They can contain all [unit] tags, to specify a variation of different gender for a unit.

See Also