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, 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 top level tags [multiplayer], [test], and [scenario] are addon module tags that are all formatted the same way. The difference between these tags is the way that the scenarios they describe are accessed.

The keys id and next_scenario affect how scenarios can be accessed. Whenever a scenario is won, the scenario with id=next_scenario of the same tag type will be played. Units from the first scenario will be available for recall in the second.

Some scenarios can be played without playing other scenarios first (in this case there is nothing on the recall list). These scenarios are called initial scenarios.

A list of initial scenarios, and how to access them:

• All [multiplayer] scenarios (without allow_new_game=no) are initial scenarios listed in the multiplayer scenario selector screen (accessed by the "multiplayer" button).
• Any [test] scenario is an initial scenario. A test scenario can be accessed by running the game in test mode. (note: this is NOT the same as debug mode. It can be accessed using -t or --test followed by an optional scenario ID which defaults to 'test'.) (Version 1.13.8 and later only) It can also be accessed by assigning a hotkey to the "Test Scenario" command in hotkey preferences, then pressing that hotkey at the title screen. This will bring up a list of interactive test scenarios to choose from. (Automated test scenarios used for unit testing are excluded from this list but can still be run from the command-line.)
• Any [scenario] scenario with an id listed in the value of first_scenario in a campaign tag (see CampaignWML) is an initial scenario accessed by selecting that campaign after clicking on the "campaign" button.

The [scenario] tag

The following keys and tags are recognized in [scenario] tags, in addition to all the common addon module keys and tags:

• next_scenario: The id of the scenario to load when the current one is won. This can be changed dynamically, to build non-linear campaigns.
• map_data: inputs valid Wesnoth map data. See BuildingMaps for a description of the Wesnoth map syntax.
• map_file: (Version 1.14.3 and later only) path to a file containing Wesnoth map data. This is the recommended way to reference a map in a scenario. The version number 1.14.3 is not a typo; it was included but buggy in earlier 1.14.x releases.
  • (Version 1.15.3 and later only) the file can be found via [binary_path], as documented for [replace_map].
• include_file: (Version 1.17.19 and later only) path to a WML file; the contents of this file is merged into the scenario tag. This can be used for scenario files created by the map editor prior to version 1.17.19, for example. As with map_file, the binary path is searched for this file, but it looks in the scenarios directory instead of the maps directory.
• turns: sets an event on turn turns causing the player to lose. Use -1 to have no turn limit. Default value is -1 on wesnoth-1.13 and 100 on wesnoth-1.12. See also EventWML
• turn_at: the turn to start on (default=1)

  Note that none of the regular start-of-turn behavior, including poison damage, healing, income and refreshing unit movement and status, will occur before the start of turn 2. All start-of-turn WML events will still be fired, however.

• random_start_time: controls random starting time of day. Possible values are yes and no or list of possible start times; starting from 1 to number of times. for example random_start_time=2,3,5,6 (default depends on version and mp/sp, better include this key)
• music: the music file relative to ./music/ to play during the scenario
• [music]: specifies the music tracks to play during this scenario, see MusicListWML.
• defeat_music: specifies a comma-separated list of music tracks which may be chosen to play on defeat. If not provided, the default in GameConfigWML is used instead. May be overridden by endlevel clauses.
• victory_music: specifies a comma-separated list of music tracks which may be chosen to play on victory. If not provided, the default in GameConfigWML is used instead. May be overridden by endlevel clauses.
• theme: the name of the UI theme that should be used when playing this scenario. Valid ids to use can be found in the files in data/themes. Cutscene and Cutscene_Minimal can be useful for dialog only scenarios.
• victory_when_enemies_defeated: when this is set to yes (default), the player wins once all non-allied units with canrecruit=yes (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.) See Also SideWML. When this value is true the following keys can be used:
  • carryover_percentage: by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
  • carryover_add: if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.
• remove_from_carryover_on_defeat: when this is set to yes (default), for sides who got defeated (according to the side.defeat_condition), carryover will be removed.
• 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.
• do_healing: (Version 1.15.0 and later only) when set to yes, the engine will not skip healing at the first sides turn and will do the healing just like every other turn.
• [story]: describes the intro screen. See IntroWML
• [label]: sets a label
  • x, y: location to set label
  • text: the label
• [item]: places an item on map. See InterfaceActionsWML.
• [time]: how a day should progress. See TimeWML
• current_time: The time of day slot number (starting from zero) active at scenario start.
• [time_area]: how a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] tags in the [scenario] tag
  • takes x and y coordinates.
  • [time]: how a day should progress in those locations. See TimeWML
  • current_time: The time slot number (starting with zero) active at the creation of the area.
  • time areas can be used in events, assigned identifiers, and removed at discretion. They also accept complete Standard Location Filters. See DirectActionsWML.
• [side]: describes one player. See SideWML
• 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
• TerrainGraphicsWML: Scenarios can define custom terrain rules for the rendering of the map.
• Color palettes

The [multiplayer] tag

The following keys and subtags are additionally recognized in [multiplayer] scenarios:

• force_lock_settings: provides a default value for SideWML lock attributes and forces the "Use map settings" to be checked and disabled. This is useful if author wants to limit game customization in order to keep the scenario/campaign balanced. Individual options can still be enabled if this key is set to yes. E.g. color selection can be enabled by explicitly setting color_lock=no in SideWML.
• new_game_title: if provided will be used instead of name for campaign entry points.
• allow_new_game: (default=yes) allow/prevent the scenario to be listed in the game configuration screen. This is intended for multiplayer campaigns with multiple entry points.
• allow_era: a list of era ids. Only the eras with matching ids will be allowed to be played with this scenario.
• disallow_era: a list of era ids. Eras with matching ids will not be allowed to be played with this scenario. Cannot be used in parallel with allow_era.
• ignore_incompatible_era: a list of era ids. The eras with matching ids will be considered compatible with this scenario regardless their dependencies.
• allow_modification: same as allow_era, but for modifications.
• disallow_modification: same as disallow_era, but for modifications. Cannot be used in parallel with allow_modification.
• ignore_incompatible_modification: same as ignore_incompatible_era, but for modifications.
• force_modification: a list of modification ids (id key in [modification]). The specified modifications must be enabled to play this scenario.
• require_scenario: (Version 1.13.0 and later only) In a multiplayer scenario, this indicates that the scenario file is not enough (you have custom assets like terrain or additional unit art) and other player must download the full add-on not just the scenario WML to join a game. This will also mean that the addon_min_version attribute will control the minimum version number of your add-on which is compatible with this version.
• mp_village_gold: (Version 1.13.9 and later only) default value for the corresponding attribute in [side]
• mp_village_support: (Version 1.13.9 and later only) default value for the corresponding attribute in [side]
• mp_shroud: (Version 1.13.9 and later only) default value for the corresponding attribute in [side]
• mp_fog: (Version 1.13.9 and later only) default value for the corresponding attribute in [side]

The [test] tag

The following keys and subtags are additionally recognized in [test] scenarios:

• is_unit_test: (Version 1.13.8 and later only) If set to 'yes', this scenario will not appear in the list of test scenarios. The list of test scenarios can be reached from the titlescreen via the Start Test Scenario hotkey. This hotkey is not set by default.

The tags documented in TestWML are enabled by an #ifdef TEST conditional, and it's a reasonable assumption that any [test] tag will itself be inside an #ifdef TEST conditional.

Defining the Map

There are several possible ways to define the map for a scenario. First of all, the game supports two different types of map: a "plain map", which typically has a .map extension (or occasionally .mask when used as a terrain mask), and a "scenario map", which has a .cfg extension.

A common practice is to include the map data directly into the scenario. If you're using a plain map, that looks like this:

[scenario]
    map_data="{~add-ons/Your_Addon/maps/the-file.map}"
[/scenario]

This uses the WML preprocessor to directly include the contents of the map file. If you're using a scenario map, it instead looks like this:

[scenario]
    {~add-ons/Your_Addon/maps/the-file.cfg}
[/scenario]

Another way to specify the map is to use map_file, which resolves the map against the binary path to locate the file. This looks the same for either a plain map or a scenario map:

[scenario]
    map_file="the-file.map"
[/scenario]

The last way to specify a map is to use a generator.

Scenario End Conditions

In this section we will give a more precise explanation of things that can cause a scenario to end.

• At the end of every turn, the turn number will be compared with the turn limit.
  • If we pass the limit, the time over event will fire. If turns are not added by WML in response to this event, then the scenario will immediately end in defeat. EventWML#The_.27name.27_Key_.28Mandatory.29
• At the beginning of any turn, and at the end of any user or ai action, the victory conditions will be checked. This will result either in the scenario ending or continuing. The procedure for this is as follows:
  • Every side will have its defeat_condition evaluated based on the units it currently has on the board. SideWML
    • At this time, villages of defeated sides will be unflagged, and if remove_from_carryover_on_defeat = yes then their carryover will be cleared as well.
  • If any two not-defeated sides are enemies, the scenario will continue.
    • At this time, the enemies defeated event will fire.
  • Furthermore, if victory_when_enemies_defeated=no and there exists a human controlled side, then the scenario will continue.
    • The human controlled side may be local or remote, for networked mp play.
  • If neither of these conditions is met then the scenario will end.
    • In victory or defeat according to whether a local human-controlled side is not defeated.

See Also

• EventWML
• ReferenceWML