Difference between revisions of "ReferenceWML"

From The Battle for Wesnoth Wiki
(Other)
m (Other: added PreprocessorRef)
(47 intermediate revisions by 29 users not shown)
Line 2: Line 2:
 
== The Wesnoth Markup Language ==
 
== The Wesnoth Markup Language ==
  
The Wesnoth Markup Language (WML) is used to code almost everything in Wesnoth,
+
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]]).
including scenarios, units, savefiles, and the user interface layout.
 
  
This page is a collection of pointers to different common WML structures.  See [[AlphabeticalWML]] for a quick listing of
+
This page is a collection of pointers to different common WML structures.
all WML tags.  The more
 
comprehensive [[BuildingScenariosIndex]] lists tags and keys.
 
  
See [[BuildingScenarios]], [[BuildingCampaigns]], [[BuildingUnits]] and [[CreatingNewUnits]]
+
See [[BuildingScenarios]], [[BuildingCampaigns]] and [[BuildingUnits]]
 
for a tutorial style overview.
 
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 ==
 
== How WML works ==
  
 +
* [[SyntaxWML]] Description of WML syntax, and how to use variables
 
* [[PreprocessorRef]] the WML preprocessor syntax
 
* [[PreprocessorRef]] the WML preprocessor syntax
** [[UtilWML]] utility macros defined in utils.cfg
+
* [[GrammarWML]] A more formal definition of the WML syntax. More useful for implementing a WML parser than for writing WML documents.
* [[SyntaxWML]] the language syntax.
 
** [[VariablesWML]] how to use WML variables
 
  
 
== WML toplevel tags ==
 
== WML toplevel tags ==
  
* [[GameConfigWML]] the top level [game_config] tag
+
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.
* [[UnitsWML]] the top level [units] tag
+
 
** [[UnitWML]] how to describe a unit type
+
* [[GameConfigWML]] the top level '''[game_config]''' tag
** [[AnimationWML]] how to animate units in 1.0
+
* [[UnitsWML]] the top level '''[units]''' tag
** [[AnimationWML1.1]] how to animate units in 1.1
+
** [[UnitTypeWML]] how to describe a unit type
* [[CampaignWML]] the top level [campaign] tag
+
** [[AnimationWML]] how to animate units
* [[ScenarioWML]] the top level tags [scenario], [multiplayer], [test], and [tutorial]
+
* [[CampaignWML]] the top level '''[campaign]''' tag
 +
* [[CoreWML]] the top level '''[core]''' tag
 +
* [[ScenarioWML]] the top level tags '''[scenario]''', '''[multiplayer]''', '''[test]''', and '''[tutorial]'''
 
** [[EventWML]] how to describe an event
 
** [[EventWML]] how to describe an event
 
** [[SideWML]] how to describe a side
 
** [[SideWML]] how to describe a side
Line 33: Line 35:
 
** [[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
 +
* [[EraWML]] the top level '''[era]''' tag
 +
* [[TerrainWML]] the top level '''[terrain_type]''' tag
 +
* [[TerrainGraphicsWML]], the top level '''[terrain_graphics]''' tag
 +
* [[ThemeWML]] the top level '''[theme]''' tag
 +
* [[LanguageWML]] the top level '''[language]''' tag
 +
* [[LocaleWML]] the top level '''[locale]''' tag
 +
* [[HelpWML]] the top level '''[help]''' tag
 +
* [[BinaryPathWML]] the top level '''[binary_path]''' 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
 
* [[SavefileWML]] a description of the format of savegames
** [[ReplayWML]] a description of the format of player actions such as moving a unit.
+
** [[ReplayWML]] a description of the format of player actions such as moving a unit
 
** [[StatisticalScenarioWML]] used to generate statistics of a savegame
 
** [[StatisticalScenarioWML]] used to generate statistics of a savegame
 
* [[PblWML]] a description of the format of server-uploadable campaigns
 
* [[PblWML]] a description of the format of server-uploadable campaigns
* [[EraWML]] the top level [era] tag
+
* [[MultiplayerWML]] a description of the WML network protocol for the Wesnoth server
* [[TerrainWML]] the top level [terrain] tag
+
* [[SchemaWML]] a description of WML files that define the structure of other WML files
* [[TerrainGraphicsWML]], the top level [terrain_graphics] tag
+
* [[DiffWML]] used to describe structural differences between preprocessed WML documents
* [[ThemeWML]] the top level [theme] tag
+
* [[GUIToolkit]] creating dialogs
* [[LanguageWML]] the top level [language] tag
 
* [[HelpWML]] the top level [help] tag
 
* [[BinaryPathWML]] the top level [binary_path] tag
 
* [[FontsWML]] the top level [fonts] tag
 
  
 
== Other WML tags ==
 
== Other WML tags ==
Line 50: Line 61:
 
* [[EventWML]] how to describe an event
 
* [[EventWML]] how to describe an event
 
** [[FilterWML]] the construct to filter on units, locations, and weapons
 
** [[FilterWML]] the construct to filter on units, locations, and weapons
** [[DirectActionsWML]] actions that directly affect gameplay: for example creating a unit
+
** [[ActionWML]] to describe the actions which occur when the event is fired
** [[InternalActionsWML]] actions that WML uses internally: for example storing a variable
+
*** [[ConditionalActionsWML]] actions that encapsulate conditional filters and the actions to execute if the conditions are met
** [[InterfaceActionsWML]] actions that do not affect gameplay: for example displaying a message
+
*** [[DirectActionsWML]] actions that directly affect gameplay: for example creating a unit
* [[SingleUnitWML]] how to describe a unit
+
**** [[SingleUnitWML]] how to describe a unit
 +
*** [[InternalActionsWML]] actions that WML uses internally: for example storing a variable
 +
*** [[InterfaceActionsWML]] actions that do not affect gameplay: for example displaying a message
 +
*** [[LuaWML]] how to code actions with the Lua language
 
* [[AiWML]] how to describe parameters for AI
 
* [[AiWML]] how to describe parameters for AI
 
* [[EffectWML]] the construct to modify a unit
 
* [[EffectWML]] the construct to modify a unit
 
* [[AbilitiesWML]] a list of the different abilities a unit or weapon can have
 
* [[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
 
* [[DescriptionWML]] the structure of WML coded menus like the difficulty chooser of campaigns
 +
* [[EditorWML]] tags controlling the post-1.4 editor's behavior
 +
 +
== Predefined macros ==
 +
 +
Wesnoth ships with a library of predefined macros you should find useful in writing your own WML.
 +
* [https://www.wesnoth.org/macro-reference.html WML Macros] - description of all such macros.
  
 
== Other ==
 
== Other ==
Line 63: Line 83:
 
* [[ReferenceWMLSyntax]] how this wiki and the pages it links to should be formatted
 
* [[ReferenceWMLSyntax]] how this wiki and the pages it links to should be formatted
 
* [[ConventionsWML]] how to make your WML more readable
 
* [[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.
 
* [[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.
 
* [[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.
 
* [[CampaignServerWML]] is used when managing contributed campaigns on the campaign server.
* [[ImagePathFunctionWML]] is used when applying the team-color function to images.
+
* [[ImagePathFunctions]] are used when applying the color function to images, such as marking units as belonging to a team or in TerrainGraphics.
 +
* [[Pango formatting]] shows ways to enrich descriptions (pango markup, which can generate basic html tags like <nowiki><b>, <i>, <span></nowiki> and others).
 +
* [[Wesnoth_Formula_Language]] (WFL) often used with $() formulas.
 +
* [[PreprocessorRef|Syntax of preprocessor mini-language]] : symbols, macros, file inclusions...
  
 
== See Also ==
 
== See Also ==
  
 
* [[BuildingMaps]] the text-based format for Wesnoth maps
 
* [[BuildingMaps]] the text-based format for Wesnoth maps
* [[TerrainLettersWML]] a list of all terrains
+
* [[TerrainCodesWML]] a list of all terrains
 
* [[MultiHexTutorial]] a description of the multi-hex tiling system
 
* [[MultiHexTutorial]] a description of the multi-hex tiling system
 
+
* [[IGNFileFormat]] a description of the ignore file format
 
+
* [[CompatibilityStandards#Deprecation_levels_-_When_to_remove_deprecated_features|DeprecationLevels]]
  
 
[[Category: WML Reference]]
 
[[Category: WML Reference]]

Revision as of 13:00, 31 October 2019

[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

  • SyntaxWML Description of WML syntax, and how to use variables
  • PreprocessorRef the WML preprocessor syntax
  • GrammarWML A more formal definition of the WML syntax. More useful for implementing a WML parser than for writing WML documents.

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
  • MultiplayerWML a description of the WML network protocol for the Wesnoth server
  • SchemaWML a description of WML files that define the structure of other WML files
  • DiffWML used to describe structural differences between preprocessed WML documents
  • GUIToolkit creating dialogs

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

Predefined macros

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

Other

See Also