Difference between revisions of "UnitTypeWML"

From The Battle for Wesnoth Wiki
(side menu)
(The [unit] tag: wikify table)
Line 7: Line 7:
  
 
The following key/tags are recognized:
 
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]].
+
{| class="gallery" style="text-align:left;"
* ''name'' (translatable) displayed in the Status Table for units of this type.
+
|-
* ''race'' See '''[race]''', [[UnitsWML]].  Also used in standard unit filter (see [[FilterWML]]).
+
! [[ability]]
* ''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.
+
| a list of the unit's abilities. See [[AbilitiesWML]] for a description of abilities.
* ''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.
+
! [[advancefrom]]
* ''hitpoints'' the maximum HP that the unit has, and the HP it has when it is created.
+
| 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:<br> ** ''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.<br>** [[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.
* ''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.
+
! [[advanceto]]
* '''[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:
+
| 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.
** ''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.
+
! alignment
* ''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.
+
| how the unit's damage should be affected by its lawful bonus (See [[TimeWML]]).
* ''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]]).
+
|-
* ''zoc'' {{DevFeature}} if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).
+
! cost
* ''alignment'' how the unit's damage should be affected by its lawful bonus (See [[TimeWML]]).
+
| 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.
* ''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,
+
! experience
** 'fighter' Melee fighter,
+
| 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.
** 'archer' Ranged fighter,
+
|-
** 'mixed fighter' Melee and ranged fighter, and
+
! gender
** 'healer' Specialty 'heals' or 'cures'.
+
| 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.
* ''unit_description'' (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
+
|-
* ''movetype'' See '''[movetype]''', [[UnitsWML]].
+
! hitpoints
Note that the tags '''[movement_costs]''', '''[defense]''', and '''[resistance]''' can be used to modify this movetype.
+
| the maximum HP that the unit has, and the HP it has when it is created.
 
+
|-
 +
! 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]].
 +
|-
 +
! 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]]).
 +
|-
 +
! movement
 +
| the number of move points that this unit recieves each turn.
 +
|-
 +
! movetype
 +
| See '''[[movetype]]''', [[UnitsWML]]. Note that the tags '''[[movement_costs]]''', '''[[defense]]''', and '''[[resistance]]''' can be used to modify this movetype.
 +
|-
 +
! name
 +
|(translatable) displayed in the Status Table for units of this type.
 +
|-
 +
! 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.
 +
|-
 +
! race
 +
| See '''[race]''', [[UnitsWML]].  Also used in standard unit filter (see [[FilterWML]]).
 +
|-
 +
! unit_description
 +
| (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
 +
|-
 +
! 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:<br> ** 'scout' Fast,<br> ** 'fighter' <br>Melee fighter, ** 'archer' Ranged fighter,<br> ** 'mixed fighter' Melee and ranged fighter, and<br> ** 'healer' Specialty 'heals' or 'cures'.
 +
|-
 +
! zoc
 +
| {{DevFeature}} if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).
 +
|}
 
==== After max level advancement (AMLA) ====
 
==== After max level advancement (AMLA) ====
 
* '''[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.
 
* '''[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.

Revision as of 11:01, 21 March 2006

[edit]WML Tags

A:

abilities, about, add_ai_behavior, advance, 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, attack_anim, attacks, avoid;

B:

base_unit, berserk, binary_path, break, brush;

C:

campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_range, command (action, replay), continue, criteria;

D:

damage, 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, era, event, 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_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, for, foreach, frame;

G:

game_config, get_global_variable, goal, gold, gold_carryover;

H:

harm_unit, has_ally, has_attack, has_unit, 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), illuminates, image, 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, portrait, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, 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_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resource, return, role, rule;

S:

save, scenario, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, set_menu_item), show_objectives, side, skirmisher, 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_type, store_unit_type_ids, store_villages, story, swarm, switch, sync_variable;

T:

target, team, teleport (ability, action), teleport_anim, terrain, terrain_defaults, terrain_graphics, terrain_mask, terrain_type, test, test_condition, text_input, textdomain, theme, then, tile, time, time_area, topic, toplevel, trait, transform_unit, traveler, true, tunnel, tutorial;

U:

unhide_unit, unit, 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

Each [unit] tag defines one unit type.

Unit animation syntax is described in AnimationWML.

The following key/tags are recognized:

After max level advancement (AMLA)

  • [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.
    • require_amla Template:DevFeature An optional list of AMLA id keys that act as prerequisites for this advancement to become available. Order is not important, and an AMLA id can be repeated any number of times to indicate that another advancement must be chosen several times before this advancement option will become available.
      • example: require_amla=tough,tough,incr_damage assumes there exist other [advancement] options called id=tough and id=incr_damage. Once tough is chosen twice and incr_damage is chosen once, then the current [advancement] will become available.
      • require_amla=tough,incr_damage,tough is an equivalent way of expressing this.
    • [effect] A modification applied to the unit whenever this advancement is chosen. See EffectWML

Attacks

  • [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". Template:DevFeature: range can be anything. Standard values are now "melee" and "ranged". From now on, short and long will be treated as totally different ranges. You can create any number of ranges now (with any name), and units can only retaliate against attacks for which they have a corresponding attack of the same range. This value is translatable.
    • damage the damage of this attack
    • number the number of strikes per attack this weapon has

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

    • attack_weight helps the AI to choose which attack to use when attacking; highly weighted attacks are more likely to be used. Template:DevFeature: Setting it to 0 disables the attack on attack
    • 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. Template:DevFeature: Setting it to 0 disable the attacks on defense
    • [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. Variations are invoked with an [effect] tag. They are currently used for graphical variations (giving character sprites new weapons) but theoretically you could do anything with it.
    • variation_name The name of the variation.
All other keys in [variation] are the same as for [unit] itself.
  • [male], [female] They can contain all [unit] tags, to specify a variation of different gender for a unit.

See Also