SyntaxWML

Other languages:

• English
• 简体中文

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

D: 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;

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, fonts, for, foreach, found_item, 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, resolution, 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 (action, scenario), 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 Wesnoth Markup Language (WML) is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout. WML files are simple, human-readable text files, usually with the .cfg extension, with similarities to INI files and XML. For guidelines on keeping these files easily human-readable, see ConventionsWML.

Tag and Attribute Structures

WML has a syntax containing two basic elements: tags and attributes. Furthermore, attributes consist of keys and values. For example:

[tag]
    key=value
[/tag]

Tags are used to partition information, while the data is contained in the attributes. Keys identify the type of data to be stored and values are the actual data stored. When WML is processed, the tag identifies some unit of information, such as an action to perform or even an entire campaign. This gives a context for the attributes within the tag. For each key=value line within a tag, the attribute identified by key has its data set to value. Also allowed inside a tag is another tag. The inner tag is considered the child of the outer tag, as in the following example.

[parent_tag]
    key1=value1
    [child_tag]
        key2=value2
    [/child_tag]
[/parent_tag]

Every tag describes something different about the game; different tags work differently, with the allowed tags defined by context. There are several "top-level tags" that are allowed when not inside any other tag, and each tag defines which child tags (and which keys) it recognizes. Unrecognized tags and keys, such as the result of typos, sometimes produce error messages, but at other times they are ignored. The WML schema defines what is allowed and where. Although it's not designed to be read by humans, you can use it to automatically detect if you've done something wrong even in contexts where unrecognized keys and tags would be ignored, though it still won't work in contexts where you're allowed to define the contents however you like.

Keys should not be confused with variables! A common mistake among beginners is to make up undocumented key names. Instead, consult the WML Reference to find allowed key names for each tag. For a list of all tags with links to their documentation, see the "WML Tags" navigation box.

Also, tag and key names follow a special format. They will contain only alphanumeric characters and underscores; in particular, they cannot contain +, -, or whitespace. The values, however, may contain such characters when needed. A key or tag name beginning with a digit or even consisting of entirely digits is permitted. Tag and key names are case sensitive.

Tag Amendment Syntax

Inserting a plus sign (+) before a tag name allows one to append to an earlier tag (the most recent with the same name) rather than starting a new tag. This allows attributes to be added or replaced.

[tag]
    key=value
[/tag]
[+tag]
    key=value
[/tag]

• All keys in the +tag will be set to the given values. If the keys did not exist in the most recent [tag] then they are added to that [tag]; otherwise their values will replace the old values in the most recent [tag].

• Any child tags of the +tag will be appended to the children of the most recent [tag]. To be clear: none of those original child tags will be altered by this operation, since this is an "append" and not a "merge."

• It is even possible to make tag amendments to a child tag after the parent tag has already closed. Using [+tag] syntax multiple times in a row (first for the parent, then for the child) will allow you to amend the more inward scopes.

Multiple Assignment Syntax

It is possible to set multiple attributes on a single line. This is done by listing the associated keys, followed by an equal sign, followed by the desired values.

[tag]
    key1,key2,key3=value1,value2,value3
[/tag]

would be the same as:

[tag]
    key1=value1
    key2=value2
    key3=value3
[/tag]

• If there are extra keys, they will be set to an empty value. If there are extra values the last key will be set to the comma-separated list of all remaining values.
• It is recommended not to use this syntax with keys which normally interpret commas specially (such as x and y in a StandardLocationFilter), to avoid confusion on which key receives which value. However, using x,y=12,10 for single coordinates is widely used and is an exception to the recommendation.

Special Attribute Values

Although an attribute's value can be just text corresponding to the function of its key, a value can also be encoded in many other ways, each with a specific purpose.

• key = "value": a quoted value is a value surrounded by quotes. This is often unnecessary as single-line values are typically interpreted as intended. However, quotes are required in order to specify multiple-line values (a line break without quotes would otherwise end the value). Quotes may also be required to cancel the special meaning of other characters, and they prevent spaces from being stripped – without quotes, all leading and trailing spaces would be removed, and internal runs of spaces would be replaced by a single space. It is never wrong to use quotes with correct WML.
• key = _"value": a translatable value is a value that is subject to translations, and should be used for all text intended to be shown to a player (most notably seen in [story], [message], and the name= key in unit definitions). A translatable value is surrounded by quotes and preceded by an underscore (_). In terms of WML syntax, it behaves very much like a quoted value, other than being unsuitable for comparisons to other values. Translatable values are intended for display on the screen, not for internal data. See TranslationsWML and GettextForWesnothDevelopers for more information.
• key = "value1" + "value2": string concatenation is performed with the plus sign (+). If a plus sign appears outside quotes in a value, it means that the string/value on its right will be appended to the string/value on its left. To have an actual plus sign in a value, the string containing the + character must be surrounded by quotes (a quoted value or a translatable value). Quotes are not strictly necessary around the pre-concatenated values, but they are advisable so that it is easy to tell where the values begin and end and to spot some kinds of mistakes. If two non-quoted values are concatenated, they will have a space inserted between them, but if either value is quoted, no space will be inserted.
• key = "quoted ""double quoted value"" value": doubled quotes can be used to create quote marks within a quoted or translatable value. The doubled quote mark in the value produces one quote mark in the stored data and does not terminate the quoted value. (These do not necessarily need to be used in pairs.)
• key = $variable: a variable substitution sets the key to the value of the indicated WML variable. This is indicated by the dollar sign ($) and is really just a special case of general variable substitution, as variables can be substituted within other values. See VariablesWML for more information on values based on WML variables. (Note that some keys require their data to be a variable name, not the variable's value; in that case there would be no dollar sign.) Variable substitution is supported in only a few contexts, such as in IntroWML and EventWML.
• key = "$(formula-expression)": a formula expression sets the key to the value of the processed formula. This is indicated by a dollar sign ($) followed by a parenthesized expression. See Wesnoth Formula Language for more information on formula basics, data types, and built-in functions. Quotes around the formula are not strictly necessary in all cases, but they are advisable, particularly since quotes are the only way to use a plus sign (+) within a formula (without quotes, the plus sign represents string concatenation). Formula expressions are only supported where variable substitution is supported.
• key = <<value>>: similar to a quoted value but stronger: the value is hidden from the preprocessor, which will see all text therein as literal. Useful with LuaWML or whenever a literal curly brace ("{", a US-ASCII 0x7B) is needed in any text string. This can also be combined with the translatable mark, in case curly braces are needed in translatable text.

Comments

Comments are indicated by a pound sign (#) unless in double quotes. Unless the line forms a valid preprocessor directive, all text after the pound sign will be ignored by the WML engine. Note that if the beginning of the line is a valid preprocessor directive, which is then followed by another pound sign, the second pound sign will still be interpreted as a comment character. For example, this works:

#ifdef FOO
#endif # FOO

Whether or not doing so is a good idea is a stylistic choice.

It is a very good coding convention to always add a space immediately following a pound sign for every comment. Not only does it avoid accidentally calling a preprocessor directive (for example, a commented line that begins with the word “define”) but it also makes comments stand further apart from the code.

Specially-formatted comments are frequently used to give commands to the Wesnoth maintenance tools to suppress false positives and enhance their coverage, as well as for adding explanatory comments for translatable strings.

See Also

• PreprocessorRef
• ConventionsWML
• SavefileWML
• ReferenceWML