From The Battle for Wesnoth Wiki

[edit]WML Tags


abilities, about, achievement, achievement_group, add_ai_behavior, advance, 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;


base_unit, background_layer, berserk, binary_path, break, brush;


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;


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;


editor_group, editor_music, editor_times, effect, else (action, animation), elseif, endlevel, end_turn (action, replay), enemy_of, engine, entry (credits, options), era, event, extra_anim;


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;


game_config, get_global_variable, goal, gold, gold_carryover;


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;


idle_anim, if (action, animation, intro), illuminates, image (intro, terrain), init_side, insert_tag, inspect, item, item_group;


jamming_costs, join;


kill, killed;


label, language, leader, leader_goal, leadership, leading_anim, levelin_anim, levelout_anim, lift_fog, limit, literal, load_resource, locale, lock_view, lua;


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;


not, note;


object, objective, objectives, on_undo, open_help, option, options, or;


part, petrifies, petrify, place_shroud, plague, poison, portrait, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, progress_achievement, put_to_recall_list;


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;


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;


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;


unhide_unit, unit, unit_overlay, unit_type, unit_worth, units, unlock_view, unpetrify, unstore_unit, unsynced;


value, variable, variables, variant, variation, victory_anim, village, vision_costs, volume;


while, wml_message, wml_schema;



Several toplevel tags are used to define an "addon module", which is a piece of an add-on that the game loads as needed. There are several different types of addon modules, but they all share some common keys. If a game does not use any addon module from your addon, then your addon won't be parsed at all. On the other hand, if the game uses any addon module from your addon, then your entire addon will be parsed, relying on preprocessor defines to exclude parts that aren't relevant to the addon module that is to be loaded.

All of the following toplevel tags define an addon module:

  • [era] - A multiplayer era
  • [campaign] - A campaign, either single-player or multiplayer
  • [scenario] - A campaign scenario
  • [multiplayer] - A multiplayer scenario
  • [test] - A test or demo scenario
  • [modification] - A modification that can be selected in the campaign or multiplayer menu
  • [resource] - A resource that can be requested by any other addon module

Common Tags and Keys

The following tags and keys are supported in most types of addon modules:

  • id: The addon module's unique ID. It must be unique across all addon module types, so for example there cannot be a [scenario] and a [multiplayer] with the same ID.
  • addon_min_version: The minimum version of your add-on with which this content is backwards compatible. Compared with the version string given in PblWML. If addon_min_version is not explicitly specified, it means compatible only with the same version. Clients in multiplayer must have add-on versions agreeing with the addon_min_versions of each others' content in order to play, and will be prompted to update otherwise.
  • name: (translatable) The visible name for the addon module, shown in the campaign selection or multiplayer game creation menu. (Not supported for [resource] since it is never visible anywhere.)
  • description: (translatable) The detailed description for the addon module, shown in the campaign selection or multiplayer game creation menu. (Also not supported for [resource], nor for [scenario] or [test].)
  • define=SYMBOL When this addon module is active, the preprocessor symbol SYMBOL will be defined. See ifdef for how this can be used to isolate parts of the file from other addon modules. Besides the addon moduel tag, only the tags [textdomain] and [binary_path] (see BinaryPathWML) should go outside of #ifdef SYMBOL. This symbol will be defined before any .cfg is preprocessed. Note: If for some reason you don't want to place your [binary_path] outside your #ifdef SYMBOL (perhaps it's causing conflicts with other addon modules), you can use binary-path-independent paths for the textdomain and any assets that are used in the addon module tag. This looks like icon=data/add-ons/whatever/something.png – essentially, any path beginning with data/.
  • [event] - An event handler that will be registered when the addon module is active. See EventWML.
  • [lua] - Lua code that will be run when the addon module is loaded, before the preload event is fired. See LuaWML.
  • [ai]: Defines an AI algorithm that can be selected by players at the join game screen. See here for details. This is not used in single-player.
    • Note: This is not the place to define faction-specific AI parameters in an era. For that, place the [ai] tag in [multiplayer_side].
    • Note: This tag may not be supported in [resource], [scenario], or [test].
  • [options]: Custom options. See OptionWML for details. Note: This may not be supported in [resource], [scenario], or [test].
  • [load_resource]: Indicates a resource to load when this addon module is loaded.
    • id: The ID of the resource.
  • [modify_unit_type] (Version 1.15.2 and later only): Changes a unit type while this modification is active. The supported attributes are:
    • type : the id of the unit type to change.
    • set_experience : changes the unit type's max experience.
    • set_cost : changes the unit type's recruit cost.
    • set_advances_to : changes the unit type's advancements.
    • add_advancement : adds a (list of comma separated) unit type(s) to the possible advancements of this unit type.
    • remove_advancement : removes a (list of comma separated) unit type(s) from the possible advancements of this unit type.

See Also

This page was last edited on 28 March 2023, at 03:25.