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;



WML Format

(Version 1.13.2 and later only)

As of 1.13.2, the DescriptionWML format has changed to use WML tags. It goes in either a [difficulty] tag within [campaign] or an [option] tag within [message] and comprises the following attributes:

  • default: If yes, this item is the default selection (assuming no other items also have default=yes).
  • image: Optional path to an image file to display.
  • label: Text to display in the first text column.
  • description: Text to display in the second text column.

Description texts

(Version 1.15.1 and later only) Support for the image-icon plus text format in this section has been removed. It is documented here only for the benefit of people who wish to port old add-ons to the new format, documented above.

A description is a part of the value of a menu attribute. It represents a single option in the difficulty selection menu for a campaign, which consists of an image (called the icon) followed by text. When appropriate, the icon should use ImagePathFunctions to replace any magenta with a team color.

The description tag uses a special format:

  • ; if another description precedes it
  • * if it should be the default selection
  • &image=text image with one text description
  • &image=text=text2 image with two text descriptions

Single text items are always enclosed in ", and can be joined together (concatenated) with +. This allows the text to contain translatable items and span multiple lines. (Marking text with _ indicates that it is translatable.)

A sample difficulty description tag might look like this:

difficulty_descriptions="&" + "units/elves-wood/elvish-fighter.png~TC(1,magenta)" + "=" + _"Fighter" + "=" + _"(easiest)" +
	";*" + "&" + "units/elves-wood/elvish-hero.png~TC(1,magenta)" + "=" + _"Hero" +
	";" + "&" + "units/elves-wood/elvish-champion.png~TC(1,magenta)" + "=" + _"Champion" + "=" + _"(hardest)"

The utility macros (see the Macro Reference) {MENU_IMG_TXT icon text} and {MENU_IMG_TXT2 icon text text-2} can be used to create descriptions more easily. The above example would become:

difficulty_descriptions={MENU_IMG_TXT2 "units/elves-wood/elvish-fighter.png~TC(1,magenta)" _"Fighter" _"(easiest)"} +
	";*" + {MENU_IMG_TXT "units/elves-wood/elvish-hero.png~TC(1,magenta)" _"Hero"} + ";" +
	{MENU_IMG_TXT2 "units/elves-wood/elvish-champion.png~TC(1,magenta)" _"Champion" _"(hardest)"}

Alternative Description Implementation

For still greater clarity, I have the following suggestion: Before the start of the [campaign] tag, create a set of #define commands as follows:

# Image definitions
# NB Don't forget the trailing + symbols for all but the last entry.
#define EASY_IMAGE


#define HARD_IMAGE

# Difficulty ratings
#po: NB be sure to retain the = signs in the translated text.
#define EASY_TEXT


#define HARD_TEXT

Note: The above example assumes three difficulty levels, which gives six difficulty entries – three for the pictures and three for the text. If you have more or fewer than three difficulty levels, make sure that the last entry does not have a trailing plus sign and that all the others do. Note also that the first image description doesn't start with a semicolon, whereas the second and subsequent ones do. Finally, only the default difficulty entry is marked with a * character.

If you set up your difficulty strings in this way you can then use a standard difficulty_descriptions tag that you will rarely need to alter. Note that this string does not contain any plus signs. You have to have them in the difficulty ratings strings instead to avoid upsetting the Wesnoth preprocessor:


The only time you would need to alter this string is if you have more or fewer than three difficulty levels for your campaign.

Simons Mith 20:16, 18 November 2011 (UTC)

See Also

This page was last edited on 25 July 2023, at 00:01.