From The Battle for Wesnoth Wiki
Revision as of 17:03, 17 May 2009 by Alink (talk | contribs) (the [units] tag: mark [hide_help] as (development only))

[edit]WML Tags


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;


base_unit, berserk, binary_path, break, brush;


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;


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;


editor_group, editor_music, editor_times, effect, else (action, animation), elseif, endlevel, end_turn (action, replay), enemy_of, engine, entry, era, event, extra_anim;


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, full_heal;


game_config, get_global_variable, goal, gold, gold_carryover;


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;


idle_anim, if (action, animation), illuminates, image, init_side, insert_tag, inspect, item, item_group;


jamming_costs, join;


kill, killed;


label, language, leader, leader_goal, leadership, leading_anim, levelin_anim, levelout_anim, lift_fog, limit, literal, load_resource, locale, lock_view, lua;


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;


not, note;


object, objective, objectives, on_undo, open_help, option, options, or;


part, petrifies, petrify, place_shroud, plague, poison, portrait, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, put_to_recall_list;


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;


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;


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;


unhide_unit, unit, unit_overlay, unit_type, unit_worth, units, unlock_view, unpetrify, unstore_unit, unsynced;


value, variable, variables, variant, variation, victory_anim, village, vision_costs, volume;


while, wml_message, wml_schema;



the [units] tag

This tag is a top level WML tag which is in game.cfg. It defines the set of all units in Wesnoth.

The following subtags are recognized:

  • [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 movetype=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).
    • [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.
    • [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. If missing in old WML, the value of the name key will be used as id.
    • 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.
    • 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.
    • [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]: Template:DevFeature 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.
    • 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, uses:

See Also