Difference between revisions of "ReferenceWML"

From The Battle for Wesnoth Wiki
m (Removed link to BinaryWML)
(Predefined macros: Update canonical link)
(4 intermediate revisions by 3 users not shown)
Line 4: Line 4:
 
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. A major feature in WML are macros, which are alike those found in the C language and similarily are handled by a preprocessor. Implementation-wise, WML files are handled mainly by the ''config'' class (and ''simple_wml'' in [[wesnothd]]).
 
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. A major feature in WML are macros, which are alike those found in the C language and similarily are handled by a preprocessor. Implementation-wise, WML files are handled mainly by the ''config'' class (and ''simple_wml'' in [[wesnothd]]).
  
This page is a collection of pointers to different common WML structures.  See [[AlphabeticalWML]] for a quick listing of all WML tags.  The more comprehensive [[BuildingScenariosIndex]] lists tags and keys.
+
This page is a collection of pointers to different common WML structures.
  
 
See [[BuildingScenarios]], [[BuildingCampaigns]] and [[BuildingUnits]]
 
See [[BuildingScenarios]], [[BuildingCampaigns]] and [[BuildingUnits]]
Line 19: Line 19:
  
 
== WML toplevel tags ==
 
== WML toplevel tags ==
 +
 +
The following covers most of the possible toplevel tags in a typical main WML file. Some minor and dev-oriented tags (not intended for use by UMC) are omitted.
  
 
* [[GameConfigWML]] the top level '''[game_config]''' tag
 
* [[GameConfigWML]] the top level '''[game_config]''' tag
Line 32: Line 34:
 
** [[TimeWML]] how to describe a day
 
** [[TimeWML]] how to describe a day
 
** [[IntroWML]] how to describe the intro screen
 
** [[IntroWML]] how to describe the intro screen
* [[SavefileWML]] a description of the format of savegames
 
** [[ReplayWML]] a description of the format of player actions such as moving a unit
 
** [[StatisticalScenarioWML]] used to generate statistics of a savegame
 
* [[PblWML]] a description of the format of server-uploadable campaigns
 
 
* [[EraWML]] the top level '''[era]''' tag
 
* [[EraWML]] the top level '''[era]''' tag
 
* [[TerrainWML]] the top level '''[terrain_type]''' tag
 
* [[TerrainWML]] the top level '''[terrain_type]''' tag
Line 45: Line 43:
 
* [[BinaryPathWML]] the top level '''[binary_path]''' tag
 
* [[BinaryPathWML]] the top level '''[binary_path]''' tag
 
* [[FontsWML]] the top level '''[fonts]''' tag
 
* [[FontsWML]] the top level '''[fonts]''' tag
 +
* [[WesCamp#The_textdomain_declaration|Textdomains]] the '''[textdomain]''' tag
 +
 +
Some other files use the WML format, but with different tags.
 +
 +
* [[SavefileWML]] a description of the format of savegames
 +
** [[ReplayWML]] a description of the format of player actions such as moving a unit
 +
** [[StatisticalScenarioWML]] used to generate statistics of a savegame
 +
* [[PblWML]] a description of the format of server-uploadable campaigns
  
 
== Other WML tags ==
 
== Other WML tags ==
Line 62: Line 68:
 
* [[DescriptionWML]] the structure of WML coded menus like the difficulty chooser of campaigns
 
* [[DescriptionWML]] the structure of WML coded menus like the difficulty chooser of campaigns
 
* [[EditorWML]] tags controlling the post-1.4 editor's behavior
 
* [[EditorWML]] tags controlling the post-1.4 editor's behavior
 +
* [[GUIToolkit]] creating dialogs
  
 
== Predefined macros ==  
 
== Predefined macros ==  
  
 
Wesnoth ships with a library of predefined macros you should find useful in writing your own WML.
 
Wesnoth ships with a library of predefined macros you should find useful in writing your own WML.
* [http://www.wesnoth.org/macro-reference.xhtml WML Macros] - description of all such macros.
+
* [https://www.wesnoth.org/macro-reference.html WML Macros] - description of all such macros.
  
 
== Other ==
 
== Other ==
Line 78: Line 85:
 
* [[MultiplayerServerWML]] is used when communicating with the multiplayer server.
 
* [[MultiplayerServerWML]] is used when communicating with the multiplayer server.
 
* [[CampaignServerWML]] is used when managing contributed campaigns on the campaign server.
 
* [[CampaignServerWML]] is used when managing contributed campaigns on the campaign server.
* [[ImagePathFunctionWML]] is used when applying the team-color function to images.
+
* [[ImagePathFunctionWML]] is used when applying the color function to images, such as marking units as belonging to a team or in TerrainGraphics.
  
 
== See Also ==
 
== See Also ==

Revision as of 00:26, 24 July 2017

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

D:

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;

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, found_item, for, foreach, 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, 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, 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

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. A major feature in WML are macros, which are alike those found in the C language and similarily are handled by a preprocessor. Implementation-wise, WML files are handled mainly by the config class (and simple_wml in wesnothd).

This page is a collection of pointers to different common WML structures.

See BuildingScenarios, BuildingCampaigns and BuildingUnits for a tutorial style overview.


Note: this reference may contain slight inaccuracies, might not list all existing keys and tags or might contain some deprecated syntax. If you find that this reference doesn't give you the answer to how to implement some feature in WML, the most reliable way is to look at the WML code of existing units and campaigns that have done so.

How WML works

WML toplevel tags

The following covers most of the possible toplevel tags in a typical main WML file. Some minor and dev-oriented tags (not intended for use by UMC) are omitted.

Some other files use the WML format, but with different tags.

  • SavefileWML a description of the format of savegames
  • PblWML a description of the format of server-uploadable campaigns

Other WML tags

  • EventWML how to describe an event
    • FilterWML the construct to filter on units, locations, and weapons
    • ActionWML to describe the actions which occur when the event is fired
  • AiWML how to describe parameters for AI
  • EffectWML the construct to modify a unit
  • AbilitiesWML a list of the different abilities a unit or weapon can have
  • DescriptionWML the structure of WML coded menus like the difficulty chooser of campaigns
  • EditorWML tags controlling the post-1.4 editor's behavior
  • GUIToolkit creating dialogs

Predefined macros

Wesnoth ships with a library of predefined macros you should find useful in writing your own WML.

Other

  • ReferenceWMLSyntax how this wiki and the pages it links to should be formatted
  • ConventionsWML how to make your WML more readable
  • Wml_optimisation how to make your WML code more efficient
  • UsefulWMLFragments Various pieces of WML for various purposes. If you have some WML you're proud of that you think others can use, add it here.
  • Maintenance tools for wmlindent, wmllint, wmlscope
  • CommandMode commands are not strictly speaking part of WML, these could be a little hard to find so there's a link here.
  • MultiplayerServerWML is used when communicating with the multiplayer server.
  • CampaignServerWML is used when managing contributed campaigns on the campaign server.
  • ImagePathFunctionWML is used when applying the color function to images, such as marking units as belonging to a team or in TerrainGraphics.

See Also