Difference between revisions of "ScenarioWML"

From The Battle for Wesnoth Wiki
(The [scenario] tag)
(The [scenario] tag)
Line 27: Line 27:
The following keys and tags are recognized in '''[scenario]''' tags:
The following keys and tags are recognized in '''[scenario]''' tags:
* '''id''': A unique identifier for this scenario. All scenarios should have an id.
* '''id''': A unique identifier for this scenario. All scenarios must have an id.
* '''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.
* '''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.

Revision as of 16:05, 28 May 2009

[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, checkbox, choice, 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 (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_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, 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 (gui2, 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, 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, [[OptionWML|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, 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;



the toplevel tags [multiplayer], [test], [tutorial], [scenario]

The top level tags [multiplayer], [test], [tutorial] and [scenario] 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 are initial scenarios listed in the multiplayer scenario selector screen (accessed by the "multiplayer" button).
  • The [test] scenario with the attribute id=test is an initial scenario. This 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)
  • The [tutorial] scenario with the attribute id=tutorial is an initial scenario. The tutorial is accessed by clicking on the "tutorial" button.
  • 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:

  • id: A unique identifier for this scenario. All scenarios must have an id.
  • 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.
  • description: (translatable) only for multiplayer maps. Will show up as a tooltip when mousing over the minimap in the multiplayer setup screen.
  • name: (translatable) is shown in several places in the level, including the intro screen. It is also the default name for saves on the level.
  • map_data: inputs valid Wesnoth map data. See BuildingMaps for a description of the Wesnoth map syntax.
  • turns: sets an event on turn turns causing the player to lose. Use -1 to have no turn limit. See also EventWML
  • turn_at: the turn to start on (default=1)
  • 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=no)
  • 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.
  • 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.) 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.
  • 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.
  • [story]: describes the intro screen. See IntroWML
  • [label]: sets a label
    • x, y: location to set label
    • text: the label
  • [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
    • takes x and y coordinates.
    • [time], [illuminated_time]: how a day should progress in those locations. See TimeWML
    • 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
  • [event]: describes an event that may be triggered at a certain point of the scenario. See EventWML
  • 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

the following key is additionally recognized in [multiplayer] scenarios:

  • allow_new_game: (default=yes) allow/prevent the scenario to be listed in the game creation interface. This is intended for extra scenarios in multiplayer campaigns

See Also