SyntaxWML

[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;

Wesnoth syntax has two basic elements: tags and attributes. Further, attributes consist of keys and values. Tag names and keys cannot contain whitespace. Any line beginning with a pound (#) sign is considered by WML as a comment, except for preprocessor declarations beginning with #.

• [tag-name] data [/tag-name] is a tag. Tags are used to partition information. A top level tag is one that is not inside any other tag. Each top level tag describes something about the game. Different tags work differently. For information about how a certain tag works, see ReferenceWML.
• [+tag-name] data [/tag-name] means that data will be considered as part of the data for the most recent [tag-name] tag. The data of [+tag-name] will be considered as coming after all data in [tag-name], so attributes of [+tag-name] will replace attributes of the original [tag-name].
• key=value newline is an attribute, or an assignment of a value to a key. When this line is processed, the value of key for the tag that the attribute is in is set or changed to value. All text from '=' until the end of the line is considered to be part of value. Note that key is not a WML variable (with the exception of VariablesWML); the value it is set to has a use which is determined by C++ code, not WML code. In order to change the value of a WML variable, you need to use [set_variable] (see InternalActionsWML). There should be no space between the key and the '=' symbol! If there is whitespace, the attribute assignment is ignored. Note that key should contain only alphanumerics or underscores (a-zA-Z0-9_); no + or - characters are allowed.
• key1,key2,key3=value1,value2,value3 newline is a multiple assignment. 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 the same as

 key1=value1
 key2=value2
 key3=value3

Although a value can be just text corresponding to a function of its key (these values are displayed in quotes (') in ReferenceWML), a value can also be encoded:

• "multiple-line-value" a multiple-line value must be enclosed in quotes, to prevent it being interpreted as a single-line value. Note that multiple-line-value doesn't have to have multiple lines; it can simply be a single-line value enclosed in quotes for clarity.
• _ "text" is a translatable value. text is English (US) text that will be displayed in-game at some point. Gettext (see GetText) is used to determine what to display if English (US) is not the current language.
• "value-1" + "value-2" can be used to concatenate two different strings. If you want to have a value that actually has a plus sign (+) in it, you need to enclose the string containing the + character in quotes (see "multiple-line-value" above).
• "double ""quote marks"" within quote marks" can be used to create quote marks within a quoted string.
• $variable-name a variable value depends on the value of the WML variable variable-name. See VariablesWML for more information on WML-variable based values.
• $(formula-expression) a $( ... ) value depends on the value of the formula-expression when evaluated. See FormulaAI for more information on Formula Basics, Data Types, and Built-in functions.

Empty Values

Usually, wesnoth does not distinguish between a key that has not been provided, and a key that has been assigned an empty value.

Some tags permit a workaround to provide a key with an empty value. You can write

 key=$empty

where 'empty' is a WML variable that has not been assigned yet. (This is not technically an empty value, and hence wesnoth will notice that this key has been provided, but will become empty during variable substitution.)

For example, to check if a variable has been initialized, you could write

 [variable]
   name=to_be_tested
   equals=$empty
 [/variable]

However, some tags actually do the variable substitution before they check if the value is empty. This applies to some EventWML commands, including the crucial set_variable tag. For example, consider the problem of copying the value another_variable to some_variable. You might write

 [set_variable]
   name=some_variable
   value="$another_variable"
   # does not work with another_variable is empty
 [/set_variable]

The above example looks okay, because the format= key does not seem empty. However, if another_variable was empty, then wesnoth perform the substitution, resulting in format="" being an empty key. Then wesnoth will ignore the set_variable command, and some_variable would retain its value instead of becoming empty.

The workaround in this case is to write

 [set_variable]
   name=some_variable
   to_variable="another_variable"
 [/set_variable]

Example

[scenario]
        id=Elves Besieged
        [side]
                side,gold=1,100
        [/side]
        [+side]
                recruit=Elvish Fighter,Elvish Archer
        [/side]
[/scenario]

In this example, [scenario] is a top level tag. When these lines are read, WML will know that there is a scenario with the ID "Elves Besieged". Later, when WML is told to play that scenario, it will read the [side] tag and give 100 gold to side 1. Then it will read the [+side] tag. It interprets this tag as belonging to side 1, since the most recent [side] belonged to side 1. So the [+side] tag allows side 1 to recruit Elvish Fighters and Elvish Archers. (Then it will crash, as the leader of side 1 has no unit type. But this isn't really important.)

Notes: Normally the order and indentation of attributes and tags does not matter, as long as the levels within tags are not changed. So the above example could have been written:

[scenario]
         [side]
                  gold=100
                  side=1
         [/side]
         id=Elves Besieged
         [+side]
                  recruit=Elvish Fighter,Elvish Archer
         [/side]
[/scenario]

Data inside tags should be separated with tabbing; see ConventionsWML.

See Also

• PreprocessorRef
• ReferenceWML