From The Battle for Wesnoth Wiki

[edit]WML Tags


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;


base_unit, background_layer, berserk, binary_path, break, brush;


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, core, credits_group, criteria;


damage, damage_type, 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 (credits, options), era, event, experimental_filter_ability, experimental_filter_ability_active, experimental_filter_specials, 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_student, filter_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, found_item, for, foreach, frame;


game_config, get_global_variable, goal, gold, gold_carryover;


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;


idle_anim, if (action, animation, intro), illuminates, image (intro, terrain), 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, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, progress_achievement, 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_trait, remove_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resolution, resource, return, role, rule;


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;


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;


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 toplevel [theme] tag

Themes are used both for the wesnoth game and the wesnoth editor. Themes allow flexible configuration of how everything is laid out on-screen.

The following keys are recognized in [theme]:

  • id: The internal id of the theme.
  • name: Translatable theme name displayed in Preferences.
  • hidden: Boolean value (defaults to no), determines whether the theme will be displayed in Preferences or not. This can be used to prevent players from choosing themes that are not intended for use in regular gameplay.
  • description: A short description of the theme to display in Preferences.

The only tag in [theme] is [resolution], but each theme can have multiple [resolution] tags. The [resolution] tags are scanned until the first one which is of the same or lower resolution than is currently being used is found, and this is used as our theme. This allows us to define themes to work differently on different resolutions, and will allow us to support both high and low resolutions elegantly.

The following keys and tags are recognized for [resolution]:

  • width, height: dimensions in pixels

All subtags of [resolution] use the following keys:

  • rect=a,b,c,d: defines the rectangle to display on, where a,b are top-left XY co-ordinates and c,d are bottom-right XY co-ordinates. So, for example rec="0,10,20,30" would create a rectangle that has top left corner at the very left side of the screen, 10 pixels below the very top and is 20 pixels wide and tall. Each of a,b,c,d may be specified as:
    • number : absolute positions
    • = : same value as the same field in reference rect (alignment with reference)
    • +number or -number : for a and b, add this value to reference's c and d respectively (spacing from reference); for c and d, add this value to self's a and b (specify by width and height)
    • =+number or =-number : add this value to same field in reference rect (eg. consider reference as a container box)
  • xanchor, yanchor: control the behavior of how this rectangle changes as the resolution changes.
    • left: its distance from the left side of the screen always remain the same, while changes in the resolution will change its size by the same amount (top for the y axis).
    • right: its size always remain the same, as well as its distance to the right side of the screen (bottom for the y axis).
    • fixed: its co-ordinates in that axis remain constant
    • proportional: its co-ordinates multiplied by the ratio of the resolution being used to the canonical resolution.


defines where the main game display (i.e. all the hexagons and units) is displayed.


Defines the border of the main map area. It has the following keys.

  • border_size: the size of the border, the value should be between 0.0 and 0.5. The images which are used by default are sized for 0.5. If the border gets smaller the images still need the same size. They're simply cut off at the right spot.
  • background_image: the filename of the image to use as background.
  • tile_image: the filename of the image to use for the _off^_usr tile. The image in the minimal can't be controlled only the image in the main map. This image must be in the terrain directory and a png image. When specifying the image the 'terrain/' prefix and '.png' suffix _must_ be ommitted.


Determines where the mini map is displayed


Displays an image as a panel on-screen.

  • image: the image used for the panel


Displays a text label on screen.

  • prefix: a string that will be printed before the text in all languages
  • text: a text string id to be displayed
  • postfix: a string that will be printed after the text in all languages
  • icon: an image that will be displayed instead of the text if it is available
  • font_size: the size of font to use for the label


  • title: the id of the string to write on the button
  • title_literal: a string that will be displayed "as is" in all language after the title
  • image: the image to use if available
  • is_context_menu: if set to true this menu will not be placed, but displayed on a right click
  • items: comma separated list of actions to put in the menu. if there is only one action, it will be executed immediately and no menu will be displayed
    • cycle: move to next movable unit
    • endunitturn: consume this unit's move and cycle to the next one
    • leader: center on the leader
    • undo: undo last action
    • redo: redo undone action
    • zoomin: zoom the map in
    • zoomout: zoom the map out
    • zoomdefault: return to default zoom
    • fullscreen: switch fulscreen mode
    • accelerated: switch turbo mode
    • resistance: show resistance table of current unit
    • terraintable: show terrain table of current unit
    • describeunit: show unit description
    • renameunit: change unit name
    • save: save the game
    • recruit: recruit a unit
    • repeatrecruit: repeat last recruitement
    • recall: recall a unit from previous scenario
    • endturn: end current turn
    • togglegrid: toggle grid display
    • statustable: show status table
    • mute: mute all sounds
    • speak: send message to other players
    • createunit: debug create a unit on the map
    • preferences: open preference dialog
    • objectives: show objective window
    • unitlist: list units
    • statistics: show game statistics
    • quit: quit the game
    • labelterrain: label current location
    • clearlabels: clear all labels on map
    • showenemymoves: show grids reachable by the enemy
    • bestenemymoves: show grids reachable by the enemy with no zone of control
    • editnewmap: editor only start a new map
    • editloadmap: editor only loads an existing map
    • editsavemap: editor only saves the current map
    • editsaveas: editor only saves the current map, let you choose a filename
    • editsetstartpos: editor only set a starting position for a team
    • editfloodfill: editor only flood the map with a terrain
    • toggleshroud: toggle the "moving removes shroud" behaviour
    • updateshroud: removes all possible shroud
    • AUTOSAVES: expands to a list of all Auto-Save games prior to this one


This tag describes the Status Table. This tag contains many other tags, which determine where other game statistics, such as the current turn, and a description of selected units go. For instance, the [time_of_day] tag will determine where the time of day image goes. Each subtag of [status] can contain the following attributes

    • font_size: the size of font to use for the status
    • rect: the rectangle as for the main_map attribute
    • xanchor: the x-wise anchoring as for the main_map attribute
    • yanchor: the y-wise anchoring as for the main_map attribute
    • prefix: the string to display before the actual status, this is the string id for internationalisation
    • prefix_literal: a string to put after the prefix, but before the label for all languages.
    • postfix_literal: a string to put after the status
    • postfix: the string to display after the postfix_literal, this is the string id for internationalisation

the following tags are recognized for [status]:

  • [unit_description]: the user description of the current unit. Note: this tag is now obsolete
  • [unit_name]: the user description of the current unit
  • [unit_type]: the type of the current unit
  • [unit_race]: the race of the current unit
  • [unit_level]: the level of the current unit
  • [unit_side]: the side of the current unit (flag)
  • [unit_traits]: the traits of the current unit
  • [unit_status]: the status of the current unit
  • [unit_alignment]: the alignment of the current unit
  • [unit_abilities]: the abilities of the current unit
  • [unit_hp]: the HP of the current unit
  • [unit_xp]: the XP of the current unit
  • [unit_moves]: the moves remaining for the current unit
  • [unit_weapons]: the attacks of the current unit
  • [unit_image]: the icon for the current unit
  • [unit_profile]: the portait for the current unit
  • [unit_advancement_options]: the advancement(s) of the current unit appear in the tooltip of this element
  • [time_of_day]: the time of day on the current location
  • [turn]: the turn number and turn remaining
  • [gold]: the gold remaining
  • [villages]: the number of villages owned
  • [num_units]: the number of units owned
  • [upkeep]: the money needed to keep your units every turn
  • [expenses]: the money lost each turn when you don't have enough income
  • [income]: the income per turn (can be positive)
  • [terrain]: the text description of the current terrain
  • [position]: the current terrain's position
  • [side_playing]: the current playing side (flag)
  • [observers]: the current observers

See Also

This page was last edited on 11 April 2023, at 23:21.