Difference between revisions of "ReferenceWML"

From The Battle for Wesnoth Wiki
(Replace WesCamp link for [textdomain])
m (WML toplevel tags: minor formatting)
 
(10 intermediate revisions by 6 users not shown)
Line 15: Line 15:
 
== How WML works ==
 
== How WML works ==
  
* [[SyntaxWML]] Description of WML syntax, and how to use variables
+
* [[SyntaxWML]] Description of WML syntax
 +
* [[VariablesWML]] How to use WML variables
 
* [[PreprocessorRef]] the WML preprocessor syntax
 
* [[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.
 
* [[GrammarWML]] A more formal definition of the WML syntax. More useful for implementing a WML parser than for writing WML documents.
 +
* [[AddonsWML]] Content that can be published and downloaded via the add-ons server
  
 
== WML toplevel tags ==
 
== WML toplevel tags ==
Line 29: Line 31:
 
** [[AnimationWML]] how to animate units
 
** [[AnimationWML]] how to animate units
 
* [[CoreWML]] the top level '''[core]''' tag
 
* [[CoreWML]] the top level '''[core]''' tag
* [[AddonsWML]] the entry point for an add-on module
+
* [[CampaignWML]] the top level '''[campaign]''' tag
** [[CampaignWML]] the top level '''[campaign]''' tag
+
** [[CreditsWML]] how to describe the credits (the '''[about]''' tag)
*** [[CreditsWML]] how to describe the credits (the '''[about]''' tag)
+
* [[ScenarioWML]] the top level tags '''[scenario]''', '''[multiplayer]''', and '''[test]'''
** [[ScenarioWML]] the top level tags '''[scenario]''', '''[multiplayer]''', and '''[test]'''
+
** [[EventWML]] how to describe an event (the '''[event]''' tag)
*** [[EventWML]] how to describe an event
+
** [[SideWML]] how to describe a side (the '''[side]''' tag)
*** [[SideWML]] how to describe a side
+
** [[MapGeneratorWML]] the random map generator
*** [[MapGeneratorWML]] the random map generator
+
** [[TimeWML]] how to describe a day
*** [[TimeWML]] how to describe a day
+
** [[IntroWML]] how to describe the intro screen (the '''[story]''' and '''[part]''' tags)
*** [[IntroWML]] how to describe the intro screen (the '''[story]''' and '''[part]''' tags)
+
* [[EraWML]] the top level '''[era]''' tag
** [[EraWML]] the top level '''[era]''' tag
+
* [[ModificationWML]] the top level '''[modification]''' and '''[resource]''' tags
** [[ModificationWML]] the top level '''[modification]''' and '''[resource]''' tags
 
 
* [[TerrainWML]] the top level '''[terrain_type]''' tag
 
* [[TerrainWML]] the top level '''[terrain_type]''' tag
 
* [[TerrainGraphicsWML]], the top level '''[terrain_graphics]''' tag
 
* [[TerrainGraphicsWML]], the top level '''[terrain_graphics]''' tag
Line 52: Line 53:
 
Some other files use the WML format, but with different tags.
 
Some other files use the WML format, but with different tags.
  
* [[AchievementsWML]] the [achievement_group] and [achievement] tags.
+
* [[AchievementsWML]] the '''[achievement_group]''' and '''[achievement]''' 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
Line 59: Line 60:
 
* [[SchemaWML]] a description of WML files that define the structure of other WML files
 
* [[SchemaWML]] a description of WML files that define the structure of other WML files
 
* [[DiffWML]] used to describe structural differences between preprocessed WML documents
 
* [[DiffWML]] used to describe structural differences between preprocessed WML documents
* [[GUIToolkit]] creating dialogs
+
* [[GUIToolkit]] gives an overview of Wesnoth's current UI system and how to create user interfaces with it.
  
 
== Other WML tags ==
 
== Other WML tags ==
Line 68: Line 69:
 
*** [[ConditionalActionsWML]] actions that encapsulate conditional filters and the actions to execute if the conditions are met
 
*** [[ConditionalActionsWML]] actions that encapsulate conditional filters and the actions to execute if the conditions are met
 
*** [[DirectActionsWML]] actions that directly affect gameplay: for example, creating a unit
 
*** [[DirectActionsWML]] actions that directly affect gameplay: for example, creating a unit
**** [[SingleUnitWML]] how to describe a unit (for uses such as placing one on the map)
+
**** [[SingleUnitWML]] how to describe a unit (for uses such as placing one on the map with the '''[unit]''' tag)
 
*** [[InternalActionsWML]] actions that WML uses internally: for example, storing a variable
 
*** [[InternalActionsWML]] actions that WML uses internally: for example, storing a variable
 
*** [[InterfaceActionsWML]] actions that do not affect gameplay: for example, displaying a message
 
*** [[InterfaceActionsWML]] actions that do not affect gameplay: for example, displaying a message
 
*** [[LuaWML]] how to code actions with the Lua language (BfW 1.14 and earlier)
 
*** [[LuaWML]] how to code actions with the Lua language (BfW 1.14 and earlier)
 
*** [[LuaAPI]] how to code actions with the Lua language (BfW 1.16 and later)
 
*** [[LuaAPI]] how to code actions with the Lua language (BfW 1.16 and later)
* [[AiWML]] how to describe parameters for AI
+
* [[AiWML]] how to describe parameters for AI (the '''[ai]''' tag)
* [[EffectWML]] the construct to modify a unit
+
* [[EffectWML]] the construct to modify a unit (the '''[effect]''' tag)
 
* [[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
Line 95: Line 96:
 
* [[CampaignServerWML]] is used when managing contributed campaigns on the campaign server.
 
* [[CampaignServerWML]] is used when managing contributed campaigns on the campaign server.
 
* [[ImagePathFunctions]] (IPFs) are used when applying the color function to images, such as marking units as belonging to a team or in TerrainGraphics.
 
* [[ImagePathFunctions]] (IPFs) 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).
+
* [[Pango formatting]] shows ways to enrich descriptions using pango markup, which can use basic html style formatting tags, such as <nowiki><b>, <i>, <span></nowiki> and others.
* [[Wesnoth_Formula_Language]] (WFL) often used with $() formulas.
+
* [[Wesnoth_Formula_Language|Wesnoth Formula Language (WFL)]] often used with $() formulas.
 
* [[PreprocessorRef|Syntax of preprocessor mini-language]] : symbols, macros, file inclusions...
 
* [[PreprocessorRef|Syntax of preprocessor mini-language]] : symbols, macros, file inclusions...
  
Line 106: Line 107:
 
* [[IGNFileFormat]] a description of the ignore file format
 
* [[IGNFileFormat]] a description of the ignore file format
 
* [[CompatibilityStandards#Deprecation_levels_-_When_to_remove_deprecated_features|DeprecationLevels]]
 
* [[CompatibilityStandards#Deprecation_levels_-_When_to_remove_deprecated_features|DeprecationLevels]]
 +
* [[Environment_variables]] a cheat-sheet for CLI environment variables
 +
* Back to [[Create]]
  
 
[[Category: WML Reference]]
 
[[Category: WML Reference]]

Latest revision as of 02:47, 30 July 2024

[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

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
  • VariablesWML How to use WML 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.
  • AddonsWML Content that can be published and downloaded via the add-ons server

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.

  • AchievementsWML the [achievement_group] and [achievement] tags.
  • SavefileWML a description of the format of savegames
  • PblWML a description of the format of server-uploadable campaigns
  • 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 gives an overview of Wesnoth's current UI system and how to create user interfaces with it.

Other WML tags

  • EventWML how to describe an event
    • FilterWML the construct to filter on units, locations, sides, weapons, vision, and WML data.
    • ActionWML to describe the actions which occur when the event is fired
      • ConditionalActionsWML actions that encapsulate conditional filters and the actions to execute if the conditions are met
      • DirectActionsWML actions that directly affect gameplay: for example, creating a unit
        • SingleUnitWML how to describe a unit (for uses such as placing one on the map with the [unit] tag)
      • 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 (BfW 1.14 and earlier)
      • LuaAPI how to code actions with the Lua language (BfW 1.16 and later)
  • AiWML how to describe parameters for AI (the [ai] tag)
  • EffectWML the construct to modify a unit (the [effect] tag)
  • DescriptionWML the structure of WML coded menus like the difficulty chooser of campaigns
  • EditorWML tags controlling the post-1.4 editor's behavior
  • MusicListWML for playing music (see also Available Music for a list of what's available)

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, but they are useful for debugging it, and could be a little hard to find, so linking to them here makes sense.
  • MultiplayerServerWML is used when communicating with the multiplayer server.
  • CampaignServerWML is used when managing contributed campaigns on the campaign server.
  • ImagePathFunctions (IPFs) 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 using pango markup, which can use basic html style formatting tags, such as <b>, <i>, <span> and others.
  • Wesnoth Formula Language (WFL) often used with $() formulas.
  • Syntax of preprocessor mini-language : symbols, macros, file inclusions...

See Also

This page was last edited on 30 July 2024, at 02:47.