CampaignWML

[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;

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

Can appear in tag: [game]

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 for difficulties
• difficulty_descriptions -- (partially translatable) menu of difficulties

Preprocessor attribute:

• define -- preprocessor symbol for campaign

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

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:

[campaign]

  icon=small.png
  name= _"My Campaign"
  description= _"Hero goes somewhere and does something."
  image=large.png

  #...

[/campaign]

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 displays 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:

[campaign]

  #...

  difficulties=EASY,NORMAL,HARD
  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)"}

  #...

[/campaign]

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) |
+-------------------------------+

Campaign symbol

Each campaign must define a unique preprocessor symbol, to make program run efficiently (load data faster and use less memory). This symbol is used to include campaign-specific WML files, that is scenario files and campaign-specific macros. If you do not care about technical details, skip the following paragraph.

WML files include each other; starting with "$data/game.cfg" which includes some files that also include some files... and so on, up to all the units, campaigns, etc. There are hundreds of WML files which must be read and parsed; they consume a lot of memory and make program start slowly. To reduce this amount, scenario files are not loaded at the start of program; their inclusion is prevented by "#ifdef" preprocessor commands (see PreprocessorRef). When starting a campaing (or loading a saved game from campaign), the campaign-specific preprocessor symbol is defined, and WML files are reloaded... now including also scenario files from the current campaign (but not from other campaigns). Each campaign must define a unique preprocessor symbol, and conditionally include campaign-specific files, to support this process. Without it, the campaign would work anyway, but its files would consume memory also when not necessary, e.g. when playing some other campaign.

The define attribute must contain a unique preprocessor symbol. It should start with "CAMPAIGN_" followed by the name of campaign. For example if your campaign is called "My Campaign", you should write:

[campaign]

  #...

  define=CAMPAIGN_MY_CAMPAIGN

  #...

[/campaign]

Then, you have to use this symbol at the end of campaign WML file (after the end of [campaign] tag) to include campaign-specific files (e.g. scenarios) like this:

#ifdef CAMPAIGN_MY_CAMPAIGN
{@campaigns/My_Campaign/scenarios}
#endif

Selecting first scenario

Attribute first_scenario specifies which scenario should be started first. Its value must be the same as the value of "id" attribute of the [scenario] tag for given scenario. For example your campaign can contain:

[campaign]

  #...

  first_scenario=My_first_scenario

  #...

[/campaign]

And the corresponding scenario would contain:

[scenario]
  id=My_first_scenario

  #...

[/scenario]

Please note that the "id" attribute of the [scenario] tag does not have to be the same as the name of scenario file. Attribute first_scenario refers to the "id" attribute of the [scenario] tag, not to the filename. (However, you should include all scenario files in your campaign file; read the previous section.)

All scenarios must have unique IDs. (That is: unique in scope of their campaign.)

Campaign tag only specifies the first scenario of the campaign. The following scenarios are specified in the [scenario] tags; each scenario specifies which one will be the following.

A complete example

This is a campaign file for campaign "My Campaign"; the file path is "$userdata/campaigns/My_Campaign.cfg".

[campaign]

  icon=small.png
  name= _"My Campaign"
  description= _"Hero goes somewhere and does something."
  image=large.png
 
  difficulties=EASY,NORMAL,HARD
  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)"}

  define=CAMPAIGN_MY_CAMPAIGN

  first_scenario=My_first_scenario

  # not a complete example yet, needs [about] tags
  # actually, it is a complete 1.0 example

[/campaign]

#ifdef CAMPAIGN_MY_CAMPAIGN
{@campaigns/My_Campaign/scenarios}
#endif

See Also

• PreprocessorRef
• ScenarioWML
• ReferenceWML
• PblWML