Difference between revisions of "UnitsWML"

From The Battle for Wesnoth Wiki
(the [units] tag)
(Rearrange the page and improve organization with headers)
Line 1: Line 1:
 
{{WML Tags}}
 
{{WML Tags}}
== the [units] tag ==
 
  
This tag is a top level WML tag which is in game.cfg.
+
The [units] is a top level WML tag which is in units.cfg.
 
It defines the set of all units in Wesnoth.
 
It defines the set of all units in Wesnoth.
 +
Its primary purpose is a container for all the [unit_type] tags describing each unit type. (See [[UnitTypeWML]] for syntax.)
 +
In addition, it can contain the following tags.
  
The following subtags are recognized:
+
== [trait] ==
* '''[unit_type]''': describes one unit type. See [[UnitTypeWML]] for syntax.
 
* '''[trait]''': describes a global trait.
 
All races with the attribute '''ignore_global_traits=no''' will have this trait.
 
See '''[trait]''': below for syntax.
 
* '''[movetype]''': used to make shortcuts to describe units with similar terrain handicaps. Units from the same advancement tree should generally have the same movetype.
 
** '''name''': an ID for this movetype. Units with the attribute '''movement_type=''name''''' will be assigned this movetype.
 
** ''flies'' either 'true' or 'false'(default). A unit with ''flies=true'' does not have its image's height adjusted for different terrains.
 
** '''[movement_costs]''': describes how fast the unit moves on different terrains. The attribute '''terrain=''speed''''' means that the unit will need to use ''speed'' move points to move onto the terrain with '''name=''terrain''''' (see [[TerrainWML]]).
 
** '''[vision_costs]''': describes how far the unit clears fog and shroud on different terrains. The attribute '''terrain=''cost''''' means that the unit will need to use ''cost'' vision points to view onto the terrain with '''name=''terrain''''' (see [[TerrainWML]]). {{DevFeature1.11}}
 
** '''[defense]''': describes how likely the unit is to be hit on different terrains. The attribute '''terrain=''defense''''' means that the unit will be hit ''defense'' percent of the time in the terrain with '''name=''terrain'''''. If the defense value is negative, then the unit will be hit as though the value were positive with one difference: the number is also the best defense that the unit may have if there is more than one terrain type for the terrain the unit is on.
 
** '''[resistance]''': describes how much damage the unit takes from different types of attacks. The attribute '''type=''resistance''''' makes the unit receive '''resistance''' percent of damage, or resist '''100-resistance''' percent of damage from attacks with '''type=''type'''''. So for example, a resistance of fire=110 means, this unit will receive 110% of damage, or have a resistance of -10% as displayed in-game. A value of fire=0 would mean, the unit receives no damage and therefore has a resistance of 100%.
 
* '''[race]''': is used to make shortcuts to describe units with similar names. Units from the same advancement tree should generally have the same race. Also, units with the same race should generally be recruitable by the same sides/factions.
 
** '''id''': ID for this race. Units with the attribute '''race=''id''''' will be assigned this race. In older versions of WML, the value of the name key was used as id if the id field was missing, but this is no longer the case.
 
** '''plural_name''': user-visible name for its people (e.g. "Merfolk" or "Elves"). Currently only used in the in-game help.
 
** '''male_name''': user-visible name for the race of the male units (e.g. "Merman"). Currently only used in the in-game unit status.
 
** '''female_name''': user-visible name for the race of the female units (e.g. "Mermaid"). Currently only used in the in-game unit status.
 
** '''name''': the default value for the three keys above. The 'name' key is the default for 'male_name' and 'female_name'. 'id' and 'plural_name' '''must''' be supplied.
 
** '''description''': description of this race, used in the race page of the in-game help. Note: currently not used by all mainline races because their descriptions are not ready. But this is already supported by the engine.
 
** '''male_names''', '''female_names''': lists of names (i.e. non-translatable strings). They are inputted into the Markov name generator to generate random names. ''male_names'' describes units with '''gender=male'''; ''female_names'' describes units with '''gender=female'''.
 
** '''markov_chain_size''': (default 2) number of letters per "syllable". "Syllables" are groupings of names that the Markov name generator uses to determine names. It does this by running a probability algorithm to guess from the name list which syllables fit well together, which can start or end a name, etc.
 
** '''num_traits''': is the number of non-repeating traits each unit of this race can be assigned.
 
** '''ignore_global_traits''': 'yes' or 'no'(default). Determines whether global traits (see [traits] above) are applied.
 
** '''undead_variation''': sets the default undead variation for members of this race.
 
** '''[topic]''': describes extra help topics for this race.
 
** '''[trait]''': describes a trait for this race. :
 
*** '''id''': unique identifier
 
*** '''availability''': describes whether a trait is "musthave" for a race or is available to "any" unit in a race, including leaders, or "none" if it is not normally available, but should be kept when advancing to this unit type. (Traits not available to the advanced unit type at all, are permanently lost upon advancement.) The default is for a trait to only be available to nonleaders. Currently "any" should not be used for traits available in multiplayer. It can be used for campaign specific traits. (Note that currently "musthave" is somewhat misused to have what are really abilities (''undead'' and ''mechanical'') default from a unit type's race. Ideally someone will eventually extend ''race'' to allow for default abilities. It might also be possible to unify traits and abilities with keys to indicate how you get them and what happens to them when you advance, while allowing them to come from race, unit type and unit definitions. There are also display issues related to doing this.)
 
*** '''male_name''': text displayed in the status of unit with the trait if the unit is male.
 
*** '''female_name''': text displayed in the status of unit with the trait if the unit is female.
 
*** '''name''': text displayed in the status of unit with the trait if none of the two above is used.
 
*** '''description''': text displayed for the description of the trait.
 
*** '''[effect]''': described in [[EffectWML]].
 
  
* '''[hide_help]''': allow to hide some units from the help. Mainly useful if you can't change these units (e.g. mainline units) and thus can't add a 'hide_help=yes' key to them. The following keys and theirs contents uses an 'OR' logic between them.
+
The [trait] tag describes a trait. When it appears in the [units] toplevel, it describes a global trait, and all races with the attribute '''ignore_global_traits=no''' will have this trait.; it may also appear in other places.
** '''type''': list of unit types.
+
* '''id''': unique identifier
** '''race''': list of races. Equivalent to all unit types of these races.
+
* '''availability''': describes whether a trait is "musthave" for a race or is available to "any" unit in a race, including leaders, or "none" if it is not normally available, but should be kept when advancing to this unit type. (Traits not available to the advanced unit type at all, are permanently lost upon advancement.) The default is for a trait to only be available to nonleaders. Currently "any" should not be used for traits available in multiplayer. It can be used for campaign specific traits. (Note that currently "musthave" is somewhat misused to have what are really abilities (''undead'' and ''mechanical'') default from a unit type's race. Ideally someone will eventually extend ''race'' to allow for default abilities. It might also be possible to unify traits and abilities with keys to indicate how you get them and what happens to them when you advance, while allowing them to come from race, unit type and unit definitions. There are also display issues related to doing this.)
** '''type_adv_tree''': list of unit types. Equivalent to all these types and their advancement trees.
+
* '''male_name''': text displayed in the status of unit with the trait if the unit is male.
** '''all''': 'yes' or 'no'(default). 'yes' is equivalent to all unit types (useful before [not])
+
* '''female_name''': text displayed in the status of unit with the trait if the unit is female.
** '''[not]''': all the previous keys (except 'all') can also be used in [not] sub-tags. And you can use [not] recursively. For example, if you want to only show the Yeti and the human race except the mage tree, use:
+
* '''name''': text displayed in the status of unit with the trait if none of the two above is used.
 +
* '''description''': text displayed for the description of the trait.
 +
* '''[effect]''': described in [[EffectWML]]. More than one of these can be used.
 +
 
 +
== [movetype] ==
 +
 
 +
The [movetype] tag is used to make shortcuts to describe units with similar terrain handicaps. Units from the same advancement tree should generally have the same movetype.
 +
* '''name''': an ID for this movetype. Units with the attribute '''movement_type=''name''''' will be assigned this movetype.
 +
* '''flies''': either 'true' or 'false'(default). A unit with ''flies=true'' does not have its image's height adjusted for different terrains.
 +
* '''[movement_costs]''': describes how fast the unit moves on different terrains. The attribute '''terrain=''speed''''' means that the unit will need to use ''speed'' move points to move onto the terrain with '''name=''terrain''''' (see [[TerrainWML]]).
 +
* '''[vision_costs]''': describes how far the unit clears fog and shroud on different terrains. The attribute '''terrain=''cost''''' means that the unit will need to use ''cost'' vision points to view onto the terrain with '''name=''terrain''''' (see [[TerrainWML]]). {{DevFeature1.11}}
 +
* '''[defense]''': describes how likely the unit is to be hit on different terrains. The attribute '''terrain=''defense''''' means that the unit will be hit ''defense'' percent of the time in the terrain with '''name=''terrain'''''. If the defense value is negative, then the unit will be hit as though the value were positive with one difference: the number is also the best defense that the unit may have if there is more than one terrain type for the terrain the unit is on.
 +
* '''[resistance]''': describes how much damage the unit takes from different types of attacks. The attribute '''type=''resistance''''' makes the unit receive '''resistance''' percent of damage, or resist '''100-resistance''' percent of damage from attacks with '''type=''type'''''. So for example, a resistance of fire=110 means, this unit will receive 110% of damage, or have a resistance of -10% as displayed in-game. A value of fire=0 would mean, the unit receives no damage and therefore has a resistance of 100%.
 +
 
 +
Default keys for the [movement_costs], [vision_costs], and [defense] tags are deep_water, shallow_water, reef, swamp_water, flat, sand, forest, hills, mountains, village, castle, cave, frozen, unwalkable, fungus, and impassable. Default keys for [resistance] are blade, pierce, impact, fire, cold, and arcane.
 +
== [race] ==
 +
 
 +
The [race] tag is used to make shortcuts to describe units with similar names. Units from the same advancement tree should generally have the same race. Also, units with the same race should generally be recruitable by the same sides/factions.
 +
* '''id''': ID for this race. Units with the attribute '''race=''id''''' will be assigned this race. In older versions of WML, the value of the name key was used as id if the id field was missing, but this is no longer the case.
 +
* '''plural_name''': user-visible name for its people (e.g. "Merfolk" or "Elves"). Currently only used in the in-game help.
 +
* '''male_name''': user-visible name for the race of the male units (e.g. "Merman"). Currently only used in the in-game unit status.
 +
* '''female_name''': user-visible name for the race of the female units (e.g. "Mermaid"). Currently only used in the in-game unit status.
 +
* '''name''': the default value for the three keys above. The 'name' key is the default for 'male_name' and 'female_name'. 'id' and 'plural_name' '''must''' be supplied.
 +
* '''description''': description of this race, used in the race page of the in-game help. Note: currently not used by all mainline races because their descriptions are not ready. But this is already supported by the engine.
 +
* '''male_names''', '''female_names''': lists of names (i.e. non-translatable strings). They are inputted into the Markov name generator to generate random names. ''male_names'' describes units with '''gender=male'''; ''female_names'' describes units with '''gender=female'''.
 +
* '''markov_chain_size''': (default 2) number of letters per "syllable". "Syllables" are groupings of names that the Markov name generator uses to determine names. It does this by running a probability algorithm to guess from the name list which syllables fit well together, which can start or end a name, etc.
 +
* '''num_traits''': is the number of non-repeating traits each unit of this race can be assigned.
 +
* '''ignore_global_traits''': 'yes' or 'no' (default). Determines whether global traits (see [traits] above) are applied.
 +
* '''undead_variation''': sets the default undead variation for members of this race.
 +
* '''[topic]''': describes extra help topics for this race.
 +
* '''[trait]''': describes a trait for this race. See above for syntax.
 +
 
 +
== [hide_help] ==
 +
 
 +
The [hide_help] tag allows you to hide some units from the help. Mainly useful if you can't change these units (e.g. mainline units) and thus can't add a 'hide_help=yes' key to them. Only really useful for campaigns, not for eras. The following keys and their contents uses an 'OR' logic between them.
 +
* '''type''': list of unit types.
 +
* '''race''': list of races. Equivalent to all unit types of these races.
 +
* '''type_adv_tree''': list of unit types. Equivalent to all these types and their advancement trees.
 +
* '''all''': 'yes' or 'no' (default). 'yes' is equivalent to all unit types (useful before [not])
 +
* '''[not]''': all the previous keys (except 'all') can also be used in [not] sub-tags. And you can use [not] recursively. For example, if you want to only show the Yeti and the human race except the mage tree, use:
 
  [hide_help]
 
  [hide_help]
 
     all=yes
 
     all=yes
Line 60: Line 68:
 
* [[UnitTypeWML]]
 
* [[UnitTypeWML]]
 
* [[ReferenceWML]]
 
* [[ReferenceWML]]
 
  
 
[[Category: WML Reference]]
 
[[Category: WML Reference]]

Revision as of 19:36, 27 August 2012

[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, credits_group, 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 (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, found_item, for, foreach, 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, 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, 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 [units] is a top level WML tag which is in units.cfg. It defines the set of all units in Wesnoth. Its primary purpose is a container for all the [unit_type] tags describing each unit type. (See UnitTypeWML for syntax.) In addition, it can contain the following tags.

[trait]

The [trait] tag describes a trait. When it appears in the [units] toplevel, it describes a global trait, and all races with the attribute ignore_global_traits=no will have this trait.; it may also appear in other places.

  • id: unique identifier
  • availability: describes whether a trait is "musthave" for a race or is available to "any" unit in a race, including leaders, or "none" if it is not normally available, but should be kept when advancing to this unit type. (Traits not available to the advanced unit type at all, are permanently lost upon advancement.) The default is for a trait to only be available to nonleaders. Currently "any" should not be used for traits available in multiplayer. It can be used for campaign specific traits. (Note that currently "musthave" is somewhat misused to have what are really abilities (undead and mechanical) default from a unit type's race. Ideally someone will eventually extend race to allow for default abilities. It might also be possible to unify traits and abilities with keys to indicate how you get them and what happens to them when you advance, while allowing them to come from race, unit type and unit definitions. There are also display issues related to doing this.)
  • male_name: text displayed in the status of unit with the trait if the unit is male.
  • female_name: text displayed in the status of unit with the trait if the unit is female.
  • name: text displayed in the status of unit with the trait if none of the two above is used.
  • description: text displayed for the description of the trait.
  • [effect]: described in EffectWML. More than one of these can be used.

[movetype]

The [movetype] tag is used to make shortcuts to describe units with similar terrain handicaps. Units from the same advancement tree should generally have the same movetype.

  • name: an ID for this movetype. Units with the attribute movement_type=name will be assigned this movetype.
  • flies: either 'true' or 'false'(default). A unit with flies=true does not have its image's height adjusted for different terrains.
  • [movement_costs]: describes how fast the unit moves on different terrains. The attribute terrain=speed means that the unit will need to use speed move points to move onto the terrain with name=terrain (see TerrainWML).
  • [vision_costs]: describes how far the unit clears fog and shroud on different terrains. The attribute terrain=cost means that the unit will need to use cost vision points to view onto the terrain with name=terrain (see TerrainWML). Template:DevFeature1.11
  • [defense]: describes how likely the unit is to be hit on different terrains. The attribute terrain=defense means that the unit will be hit defense percent of the time in the terrain with name=terrain. If the defense value is negative, then the unit will be hit as though the value were positive with one difference: the number is also the best defense that the unit may have if there is more than one terrain type for the terrain the unit is on.
  • [resistance]: describes how much damage the unit takes from different types of attacks. The attribute type=resistance makes the unit receive resistance percent of damage, or resist 100-resistance percent of damage from attacks with type=type. So for example, a resistance of fire=110 means, this unit will receive 110% of damage, or have a resistance of -10% as displayed in-game. A value of fire=0 would mean, the unit receives no damage and therefore has a resistance of 100%.

Default keys for the [movement_costs], [vision_costs], and [defense] tags are deep_water, shallow_water, reef, swamp_water, flat, sand, forest, hills, mountains, village, castle, cave, frozen, unwalkable, fungus, and impassable. Default keys for [resistance] are blade, pierce, impact, fire, cold, and arcane.

[race]

The [race] tag is used to make shortcuts to describe units with similar names. Units from the same advancement tree should generally have the same race. Also, units with the same race should generally be recruitable by the same sides/factions.

  • id: ID for this race. Units with the attribute race=id will be assigned this race. In older versions of WML, the value of the name key was used as id if the id field was missing, but this is no longer the case.
  • plural_name: user-visible name for its people (e.g. "Merfolk" or "Elves"). Currently only used in the in-game help.
  • male_name: user-visible name for the race of the male units (e.g. "Merman"). Currently only used in the in-game unit status.
  • female_name: user-visible name for the race of the female units (e.g. "Mermaid"). Currently only used in the in-game unit status.
  • name: the default value for the three keys above. The 'name' key is the default for 'male_name' and 'female_name'. 'id' and 'plural_name' must be supplied.
  • description: description of this race, used in the race page of the in-game help. Note: currently not used by all mainline races because their descriptions are not ready. But this is already supported by the engine.
  • male_names, female_names: lists of names (i.e. non-translatable strings). They are inputted into the Markov name generator to generate random names. male_names describes units with gender=male; female_names describes units with gender=female.
  • markov_chain_size: (default 2) number of letters per "syllable". "Syllables" are groupings of names that the Markov name generator uses to determine names. It does this by running a probability algorithm to guess from the name list which syllables fit well together, which can start or end a name, etc.
  • num_traits: is the number of non-repeating traits each unit of this race can be assigned.
  • ignore_global_traits: 'yes' or 'no' (default). Determines whether global traits (see [traits] above) are applied.
  • undead_variation: sets the default undead variation for members of this race.
  • [topic]: describes extra help topics for this race.
  • [trait]: describes a trait for this race. See above for syntax.

[hide_help]

The [hide_help] tag allows you to hide some units from the help. Mainly useful if you can't change these units (e.g. mainline units) and thus can't add a 'hide_help=yes' key to them. Only really useful for campaigns, not for eras. The following keys and their contents uses an 'OR' logic between them.

  • type: list of unit types.
  • race: list of races. Equivalent to all unit types of these races.
  • type_adv_tree: list of unit types. Equivalent to all these types and their advancement trees.
  • all: 'yes' or 'no' (default). 'yes' is equivalent to all unit types (useful before [not])
  • [not]: all the previous keys (except 'all') can also be used in [not] sub-tags. And you can use [not] recursively. For example, if you want to only show the Yeti and the human race except the mage tree, use:
[hide_help]
    all=yes
    [not]
        type=Yeti
        race=human
        [not]
            type_adv_tree=Mage
        [/not]
    [/not]
[/hide_help]

See Also