ScenarioWML

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

During a scenario, units of a few sides fight against each other on the map for the limited number of turns. In addition to standard game rules, there are scenario-specific events. The side which succeeds to fulfill scenario objectives wins; this is end of scenario, and possibly switching to another scenario.

Though technically there are 4 types of scenarios -- multiplayer scenarios, campaign scenarios, tutorial scenarios, and test scenarios -- the diferences between them are very small. The tutorial is just another campaign, except that is does not appear in a campaign menu, but it started with a button on main screen (and it does not have difficulties; though difficulties are optional also for campaigns). Multiplayer scenarios have special settings in game menu; they allow many human-controlled players, and disallow recall. (It is not currently possible to make a multiplayer campaign, but this may change in future versions.)

The [scenario] / [multiplayer] / [tutorial] / [test] tag contains information about:

• scenario order in storyline
• map
• fighting sides
• events

The [multiplayer], [scenario], [tutorial] and [test] tags

Top-level tags; appear directly in [game].

Attributes marked [M] are valid only for the [multiplayer] tags.

General attributes:

• id -- unique identifier of scenario
• next_scenario -- the default following scenario
• name -- (translatable) name of scenario; used in intro screen, save file names, etc
• description -- [M] (translatable) description of scenario, a tooltip in the multiplayer setup screen
• turns sets an event on turn turns causing the player to lose. See also EventWML
• turn_at the turn to start on (default=1)

• theme the UI theme that should be used when playing this scenario. See Using_custom_themes_in_campaigns

• music the music file relative to ./music/ to play during the scenario

• [music] Template:DevFeature specifies the music tracks to play during this scenario, see MusicListWML. This was introduced after 1.1, obsoleting the old music key, which specifies the music to play relative to the '"music/'".

Map subtag and attributes:

• map_data inputs valid Wesnoth map data. See BuildingMaps for a description of the Wesnoth map syntax.

• [label] sets a label
  • x, y location to set label
  • text the label

• map_generation another way to generate a map. The map will be generated randomly
  • "default" the default random map generator
• [generator] if this is present, the map and scenario will be generated randomly. See MapGeneratorWML

Intro subtag:

• [story] describes the intro screen. See IntroWML

Rule attributes:

• victory_when_enemies_defeated when this is set to 'yes'(default), the player wins once all non-allied units with canrecruit=1 (aka leaders) are killed. (Currently this only controls the win condition for when all enemies are defeated; it does not prevent the player from losing if he has no leader.)

• disallow_recall when this is set to 'no'(default), the player is allowed to recall units from previous scenarios.

• experience_modifier the percentage that required XP to level up (for all units in the scenario) is multiplied by. Default 100. Note that when used in a campaign, weird things (like units being above the required XP to level up) can happen if this value is different for different scenarios.

Side subtag:

• [side] describes one player. See SideWML

Time-of-day subtags:

• [time], [illuminated_time] how a day should progress. See TimeWML
• [time_area] how a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] and [illuminated_time] tags in the [scenario] tag
  • standard location filter
  • [time], [illuminated_time] how a day should progress in those locations. See TimeWML

Event subtag:

• objectives (translatable) the text displayed in the Scenario Objectives box in-game. Now obsolete; see [objectives], InterfaceActionsWML.
• [event] describes an event that may be triggered at a certain point of the scenario. See EventWML

Ordering scenarios in campaign

The most simple solution is to build a linear sequence of scenarios; it has also the advantage of easier storytelling, and gradually increasing game difficulty. But using events, the scenarios can "hyperlink" each other freely. Author can split the story (based on player's decision or action); later join it again or provide different endings; make an optional "bonus" scenario; etc.

The scenarios may only link to scenarios of the same tag type, that is: multiplayer scenario to another multiplayer scenario, campaign scenario to another campaign scenario, tutorial scenario to another tutorial scenario, and test scenario to another test scenario.

The id attribute is the scenario identifier. The next_scenario attribute is the identifier of the following scenario. It can be overridden by a "next_scenario" attribute of an [endlevel] action (see DirectActionsWML).

• The first multiplayer scenario is the one selected from the game menu.
• The first campaign scenario is determined by a "first_scenario" attribute in [campaign] tag.
• The first tutorial scenario is the one with id=tutorial.
• The first test scenario is the one with id=test.

For example if the campaign contains the following attribute:

[campaign]

  #...

  first_scenario=My_first_scenario

  #...

[/campaign]

Then the first scenario would look like this:

[scenario]

  id=My_first_scenario
  next_scenario=My_second_scenario

  #...

[/scenario]

The last scenario has value next_scenario=null:

[scenario]

  id=My_last_scenario
  next_scenario=null

  #...

[/scenario]

The event that moves player to a bonus scenario, would look like this:

[scenario]

  #...

  [event]

    #...

    [endlevel]
       result=victory
       next_scenario=My_bonus_scenario
    [/endlevel]

  [/event]

[/scenario]

Units that survive the scenario are added to the recall list. The first scenario has an empty recall list.

Using test scenarios

Test scenario can be started directly from the system command line. The game menu and campaign menu are skipped; this saves a few seconds of time at each start; which can save a lot of time when frequently editing. So you may want to temporarily turn your campaign scenario to a test scenario:

• replace the "[scenario]" tag with "[test]" tag;
• change "id" attribute to "id=test";
• move it to "$userdata/campaigns" directory.

Note: When you install Wesnoth, it already includes a test scenario in "$data/scenario-test.cfg". You have to overwrite or delete this default test scenario (because there cannot be two test scenarios with the same "id".)

To start the test scenario, on MS Windows, make a "bat" file containing the following commands:

cd %ProgramFiles%\Wesnoth
wesnoth.exe --test --windowed

When playing test scenario it is not possible to recall units; so balancing scenario difficulty may not be accurate.

Related forum threads: 9146, 9839.

See Also

• EventWML
• ReferenceWML