Difference between revisions of "ScenarioWML"

From The Battle for Wesnoth Wiki
(rewriting + examples)
m (Reverted edit of Viliam, changed back to last version by Placid)
Line 1: Line 1:
 
{{WML Tags}}
 
{{WML Tags}}
 +
== the toplevel tags [multiplayer], [test], [tutorial], [scenario] ==
  
During a scenario, units of a few sides fight against each other on the map for the limited number of turns.
+
The top level tags '''[multiplayer]''', '''[test]''', '''[tutorial]''' and '''[scenario]''' are all formatted the same way.
In addition to standard game rules, there are scenario-specific events.
+
The difference between these tags is the way that the scenarios they describe are accessed.
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 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.
  
The [scenario] / [multiplayer] / [tutorial] / [test] tag contains information about:
+
Some scenarios can be played without playing other scenarios first
* scenario order in storyline
+
(in this case there is nothing on the recall list).
* map
+
These scenarios are called ''initial scenario''s.
* fighting sides
 
* events
 
  
== The [multiplayer], [scenario], [tutorial] and [test] tags ==
+
A list of initial scenarios, and how to access them:
  
Top-level tags; appear directly in [game].
+
* All '''[multiplayer]''' scenarios are initial scenarios listed in the multiplayer scenario selector screen (accessed by the "multiplayer" button).
  
Attributes marked [M] are valid only for the [multiplayer] tags.
+
* 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) You can speed up scenario development a lot by this when used in a clever way: Move a scenario into ~campaigns (so that it will be read even without its campaign being loaded), change it to a [test] scenario, and change the ID to 'test'. Then run Wesnoth in test mode. This saves about a minute for each time you want to test changes to your scenario. However it should not be used for balancing as there will be no recallable units...
  
General attributes:
+
* The '''[tutorial]''' scenario with the attribute '''id=tutorial''' is an initial scenario. The tutorial is accessed by clicking on the "tutorial" button.
  
* ''id'' -- unique identifier of scenario
+
* 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.
* ''next_scenario'' -- the default following scenario
+
 
* ''name'' -- (translatable) name of scenario; used in intro screen, save file names, etc
+
== The [scenario] tag ==
* ''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]]
+
The following keys and tags are recognized in '''[scenario]''' tags:
* ''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]]
+
* ''id'' A unique identifier for this scenario.
  
* ''music'' the music file relative to ''./music/'' to play during the scenario
+
* ''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.
  
* '''[music]''' {{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/'".
+
* ''description'' (translatable) only for multiplayer maps. Will show up as a tooltip when mousing over the minimap in the multiplayer setup screen. Only in >0.8.5
  
Map subtag and attributes:
+
* ''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.
 
* ''map_data'' inputs valid Wesnoth map data. See [[BuildingMaps]] for a description of the Wesnoth map syntax.
  
* '''[label]''' sets a label
+
* ''turns'' sets an event on turn ''turns'' causing the player to lose. See also [[EventWML]]
** ''x'', ''y'' location to set label
+
 
** ''text'' the label
+
* ''turn_at'' the turn to start on (default=1)
  
* ''map_generation'' another way to generate a map. The map will be generated randomly
+
* ''music'' the music file relative to ''./music/'' to play during the scenario
** "default" the default random map generator
 
* '''[generator]''' if this is present, the map and scenario will be generated randomly. See [[MapGeneratorWML]]
 
  
Intro subtag:
+
* '''[music]''' {{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/'".
  
* '''[story]''' describes the intro screen. See [[IntroWML]]
+
* ''theme'' the UI theme that should be used when playing this scenario. See [[Using_custom_themes_in_campaigns]]
  
Rule attributes:
+
* ''objectives'' (translatable) the text displayed in the Scenario Objectives box in-game. Now obsolete; see '''[objectives]''', [[InterfaceActionsWML]].
  
 
* ''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.)
 
* ''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.)
Line 58: Line 55:
 
* ''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.
 
* ''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:
+
* '''[story]''' describes the intro screen. See [[IntroWML]]
  
* '''[side]''' describes one player. See [[SideWML]]
+
* '''[label]''' sets a label
 +
** ''x'', ''y'' location to set label
 +
** ''text'' the label
  
Time-of-day subtags:
+
* '''[time]''', '''[illuminated_time]''' how a day should progress. See [[TimeWML]]
  
* '''[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
 
* '''[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
 
** standard location filter
 
** '''[time]''', '''[illuminated_time]''' how a day should progress in those locations. See [[TimeWML]]
 
** '''[time]''', '''[illuminated_time]''' how a day should progress in those locations. See [[TimeWML]]
  
Event subtag:
+
* '''[side]''' describes one player. See [[SideWML]]
  
* ''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]]
 
* '''[event]''' describes an event that may be triggered at a certain point of the scenario. See [[EventWML]]
  
=== Ordering scenarios in campaign ===
+
* ''map_generation'' another way to generate a map. The map will be generated randomly
 
+
** "default" the default random map generator
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: [http://www.wesnoth.org/forum/viewtopic.php?t=9146 9146], [http://www.wesnoth.org/forum/viewtopic.php?t=9839 9839].
 
  
 +
* '''[generator]''' if this is present, the map and scenario will be generated randomly. See [[MapGeneratorWML]]
  
 
== See Also ==
 
== See Also ==

Revision as of 19:57, 6 July 2006

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

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) You can speed up scenario development a lot by this when used in a clever way: Move a scenario into ~campaigns (so that it will be read even without its campaign being loaded), change it to a [test] scenario, and change the ID to 'test'. Then run Wesnoth in test mode. This saves about a minute for each time you want to test changes to your scenario. However it should not be used for balancing as there will be no recallable units...
  • 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.
  • 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. Only in >0.8.5
  • 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. See also EventWML
  • turn_at the turn to start on (default=1)
  • 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/'".
  • objectives (translatable) the text displayed in the Scenario Objectives box in-game. Now obsolete; see [objectives], InterfaceActionsWML.
  • 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.
  • [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
    • standard location filter
    • [time], [illuminated_time] how a day should progress in those locations. See TimeWML
  • [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

See Also