From The Battle for Wesnoth Wiki
Revision as of 14:51, 21 March 2006 by Viliam (talk | contribs) (restructured, added examples for campaign menu and difficulty menu)

[edit]WML Tags


abilities, about, 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, attack_anim, attacks, avoid;


base_unit, berserk, binary_path, break, brush;


campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_range, command (action, replay), continue, 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, 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_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, for, foreach, frame;


game_config, get_global_variable, goal, gold, gold_carryover;


harm_unit, has_ally, has_attack, has_unit, have_location, have_unit, heal_on_hit, heal_unit, healed_anim, healing_anim, heals, hide_help, hide_unit, hides;


idle_anim, if (action, animation), illuminates, image, 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, 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_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resource, return, role, rule;


save, scenario, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, set_menu_item), show_objectives, side, skirmisher, 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_type, store_unit_type_ids, store_villages, story, swarm, switch, sync_variable;


target, team, teleport (ability, action), teleport_anim, terrain, terrain_defaults, terrain_graphics, terrain_mask, terrain_type, test, test_condition, text_input, textdomain, theme, then, tile, time, time_area, topic, toplevel, trait, transform_unit, traveler, true, tunnel, tutorial;


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;



Each campaign consists of several scenarios. Those scenarios are described in their [scenario] tags. A [campaign] tag describes things related to the whole campaign, that is:

  • how campaign appears in the game campaign menu
  • electable difficulties
  • preprocessor symbol for campaign
  • ID of the first scenario
  • campaign specific credits

Please note that though scenario files are included from campaign files, the [scenario] tags do not appear inside of the [campaign] tags, but are typically included after them.

The [campaign] tag

Campaign menu attributes:

  • rank -- order of campaign in the campaign selection menu
  • icon -- small campaign image in the campaign selection menu
  • name -- (translatable) campaign name in the campaign selection menu
  • description -- (translatable) campaign description in the information pane of the campaign selection menu
  • image -- larger campaign image in the information pane of the campaign selection menu

Difficulty attributes:

  • difficulties -- comma-separated list of preprocessor symbols
  • difficulty_descriptions -- menu of difficulties

Preprocessor attribute:

  • define=CAMPAIGN_SYMBOL when this campaign is started, the preprocessor symbol CAMPAIGN_SYMBOL will be defined. See #ifdef in PreprocessorRef for how this can be used to isolate parts of the campaign file from other campaigns. Only the tags [campaign] and [binary_path] (see BinaryPathWML) should go outside of #ifdef CAMPAIGN_SYMBOL.

First scenario attribute:

  • first_scenario the ID of the first scenario in the campaign; see id in ScenarioWML

Campaign credits subtag:

  • [about] Template:DevFeature inserts your own credits into the game's list of credits. The campaign's name automatically is inserted at the top of the rolling credits followed by title/text key pairs. There can be any number of [about] tags inside a [campaign] tag. The [about] tag has the following keys:
    • title (translatable) large text used to start a new subsection (writers, artists, units, balancing) in the rolling credits
    • text (translatable, but you probably won't want to make it such) smaller text intended for the names of developers

Obsolete attributes: (do not use them)

  • id -- the internationalization key for the campaign

Campaign selection menu

Campaign selection menu displays a list of mainline and user-contributed campaigns. Campaigns are ordered by their rank attribute (lower to higher, unranked in the end). Mainline campaigns use multiples of 10 from 10 to 50. Your campaign's rank should be at least 51; but you do not have to specify it.

In the left part of dialog the icon and name of campaign are displayed. When user selects a campaign, the description and image are displayed in the right part. For example if [campaign] tag looks like this:

  name= _"My Campaign"
  description= _"Hero goes somewhere and does something."

Then the campaign selection menu will look like this:

| Select a campaign:           |                     |
| [.....] Heir to the Throne   | Hero goes somewhere |
| [.....] Son of the Black Eye | and does something. |
| [.....] Eastern Invasion     |     [ large ]       |
| [.....] The Rise of Wesnoth  |     [  .png ]       |
| [small] My Campaign          |                [OK] |

Difficulty menu

From campaign author's view, "difficulty" is a preprocessor symbol, which can be used in scenario script to make gameplay easier or harder. This is typically done by making difficulty-dependent turn limits, starting gold for enemies, recruiting lists for enemies, AI commands,... but it can be anything. Exactly one on difficulty symbols is defined during campaign.

Using difficulties in campaign in optional. It is recommend to use standard symbols "EASY", "NORMAL", "HARD", because a few standard macros use them (file "utils.cfg"; see UtilWML). The difficulties attribute is a comma-separated list of preprocessor symbols to be defined. These symbols are used internally, and are never displayed to player. (It means that campaign author can use the symbols "EASY", "NORMAL", "HARD", even if the selection box contain different names, e.g. "Hard", "Very hard", "Nightmare".) The difficulty_descriptions is a formatted string that is best created using macros "MENU_IMG_TXT" and "MENU_IMG_TXT2" like this:

  difficulty_descriptions= {MENU_IMG_TXT2 elvish-fighter.png  _"Fighter"  _"(easiest)"} + ";"
                   + "*" + {MENU_IMG_TXT  elvish-hero.png     _"Hero"                 } + ";"
                         + {MENU_IMG_TXT2 elvish-champion.png _"Champion" _"(hardest)"}

The semicolon ";" separates items in menu, and the asterisk "*" specifies the default value (see DescriptionWML). Number of rows in difficulty_descriptions must be the same as number of symbols in difficulties. The difficulty menu will look like this:

| Choose a difficulty:          |
| [fighter.] Fighter  (easiest) |
| [hero.png] Hero               |
| [champion] Champion (hardest) |

See Also