Difference between revisions of "SavefileWML"

From The Battle for Wesnoth Wiki
m (fix typo)
 
(14 intermediate revisions by 9 users not shown)
Line 1: Line 1:
−
== the format for Wesnoth savegames ==
+
{{WML Tags}}
 +
== The format for Wesnoth savegames ==
  
−
A Wesnoth savegame has two parts.
+
A Wesnoth savegame is a file stored in '''~saves/''' (See "user data directory", [[PreprocessorRef]]).
−
One is a file stored in '''~saves/''' (See "user data directory", [[PreprocessorRef]]).
+
In order to view or modify these files, the option Compressed Saves (Advanced Preferences) must be set to "No". Also, since they are not config(.cfg) files the normal coloring will not be generated. To generate coloring, simply save the file as .cfg, then open it again.
−
The other is a [save] tag in '''~save_index'''.
 
−
Each savegame describes a position in a scenario which can be loaded by pressing the "Load" button in-game.
 
  
−
In order to view or modify these files,
+
There are 3 types of savegames: start-of-scenario, replay and in-game (including autosave and out-of-sync save). The information included in a save depends on its type.
−
the option "Binary Saves" (Advanced Preferences) must be set to "No".
 
−
Also, since they are not config('''.cfg''') files the normal coloring will not be generated.
 
−
To generate coloring, simply save the file as '''.cfg''', then open it again.
 
  
−
The [save] tag is used to describe a save so that information about the save can be displayed
+
{|
−
in the "Load game" menu before the savefile is opened (loading savefiles takes a while)
+
|-
 +
| || Start-of-scenario || Replay || In-game
 +
|-
 +
| General info and statistics || Yes || Yes || Yes
 +
|-
 +
| [snapshot] || No || No || Yes
 +
|-
 +
| [replay] || No || Yes || Yes
 +
|-
 +
| [replay_start] || No || Yes || Yes
 +
|-
 +
| [carryover_sides] || No || Yes || Yes
 +
|-
 +
| [carryover_sides_start] || Yes || Yes || Yes
 +
|}
  
−
the following keys are recognized for [save]:
+
{{DevFeature1.13|0}} There are 4 types of savegames: start-of-scenario, expanded start-of-scenario, replay and in-game (including autosave and out-of-sync save). The information included in a save depends on its type.
−
* ''save'' heading of the save; displayed in bold
 
−
* ''mod_time'' a number describing when the savefile was last edited
 
−
(i.e. when the game was saved).
 
−
Display format will not be described
 
−
* ''campaign_type'' whether the scenario is a scenario or multiplayer.
 
−
Displayed as is
 
−
* ''turn'' describes which turn it is, and the number of turns allowed in the scenario.
 
−
Displayed in the format '''Turn ''turn'''''
 
−
* ''difficulty'' the difficulty level of the savegame.
 
−
Displayed in the format '''Difficulty: ''difficulty'''''
 
−
* ''leader'' a unit type.
 
−
This unit type's picture will be displayed to the left
 
−
* ''map_data'' the data for the map.
 
−
The mini-map generated by this data is displayed to the right
 
−
* ''replay''
 
−
* ''scenario''
 
−
* ''snapshot''
 
  
−
The savefile itself describes two things- a position, and a replay.
+
{|
−
Each of these is described by describing a starting position, then describing a set of actions.
+
|-
−
The '''[snapshot]''' tag has the same format as the rest of the savefile,
+
| || Start-of-scenario || Expanded Start-of-scenario || Replay || In-game
−
except that the [replay_start] keys have been moved to toplevel.
+
|-
−
It describes how the game should be loaded when "Show replay" is not selected
+
| General info and statistics || Yes || Yes || Yes || Yes
 +
|-
 +
| [snapshot] || No || No || No || Yes
 +
|-
 +
| [replay] || No || No || Yes || Yes
 +
|-
 +
| [replay_start] || No || No || Yes || Yes
 +
|-
 +
| [carryover_sides] || No || No || Yes || Yes
 +
|-
 +
| [carryover_sides_start] || Yes  || Yes || No || No
 +
|-
 +
| [scenario] || No || Yes  || No || No
 +
|}
  
−
In addition to the [snapshot] tag, the following key/tags are recognized:
+
{{DevFeature1.13|0}} There are also 2 types of Server generated replays
−
* ''label'' obsolete? It is the same as ''save'' in [save]
+
{|
−
* ''campaign_define'' when this replay is loaded, the symbol ''campaign_define'' will be stored.
+
|-
−
See also "#ifdef", [[PreprocessorRef]]
+
| || Fresh game || Start-of-scenario || Reloaded game
−
* ''campaign_type//,//scenario'' the tag type and ID of the scenario, respectively. See [[ScenarioWML]]
+
|-
−
* ''version'' the version of Wesnoth this game was saved by.
+
| General info and statistics || Yes || Yes || Yes
−
If the savegame is from a different version of Wesnoth than the one currently running, the message "This save is from a
+
|-
−
different version of the game. Do you want to try to load it?" is displayed
+
| [snapshot] || No || No || Yes
−
* ''can_recruit'' the set of unit types side 1 is allowed to recruit.
+
|-
−
* ''difficulty'' the difficulty level of the savegame.
+
| [replay] || Yes || Yes || Yes
−
Normal values are "EASY", "NORMAL", and "HARD". See [[CampaignWML]]
+
|-
−
* ''gold'' the amount of gold the player has
+
| [replay_start] || No || No || Yes
−
* ''playing_team'' the number of the team whose turn it is, starting with 0
+
|-
−
* ''turn_at'' the number of the current turn
+
| [carryover_sides] || No || No || Yes
−
* ''snapshot''
+
|-
−
* '''[variables]''' a list of the current values of all variables.
+
| [carryover_sides_start] || Yes  || Yes || No
−
The attribute '''''variable//=//value//''' means that the variable ''variable'' has the value ''value''.
+
|-
−
The tag '''[''array//]''' describes a unit stored in the array ''array'' (see [[SingleUnitWML]]).
+
| [scenario] || Yes  || Yes  || No
−
See also [[VariablesWML]]
+
|}
−
* '''[replay]''' describes what should be displayed if the option "Show replay" is selected
+
 
−
** '''[command]''' describes one action.
+
 
−
Syntax for [command] is described in [[ReplayWML]]
+
'''General info and statistics'''
−
* '''[statistics]''' describes previous scenarios
+
 
−
** ''mid_scenario'' if "false", the scenario will be reloaded and any modifications will be played with.
+
Contains general information about the scenario, campaign and version of Battle for Wesnoth the savegame is from. This information is included in all savegames.
−
** '''[scenario]''' describes basic statistics of a previous scenario.
+
Not all tags of this section are explained here.
−
See [[StatisticalScenarioWML]] for a description of [scenario]
+
 
−
* '''[unit]''' describes a unit in the recall list. See [[SingleUnitWML]]
+
* '''version''': The version of Wesnoth this game was saved by. If the savegame is from a different version of Wesnoth than the one currently running, the message "This save is from a different version of the game. Do you want to try to load it?" is displayed
−
* '''[replay_start]''' describes the position the player was in when the game started.
+
* '''campaign_type''': Whether the scenario is a scenario or multiplayer.
−
has the same keys and tags as [scenario] (see [[ScenarioWML]]).
+
* '''campaign_define''': When this replay is loaded, the symbol campaign_define will be stored. See also "#ifdef", [[PreprocessorRef]]
−
In addition to the [scenario] keys and tags, it has the following keys:
+
* '''difficulty''': The difficulty level of the savegame. Normal values are "EASY", "NORMAL", and "HARD".  
−
** ''era'' the name of the era. See [[EraWML]]
+
* '''label''':  heading of the save
−
** ''experience_modifier'' all units' maximum experience is multiplied by this number
+
* '''next_scenario''': Name of the next scenario in a campaign
−
** ''observer'' whether the player is an observer
+
* '''scenario''': Name of the current scenario
−
** ''modify_placing''
+
* '''[multiplayer]''': If the game is a multiplayer game, multiplayer information is included here
 +
* '''[statistics]''': Describes previous scenarios
 +
** '''mid_scenario''': If "false", the scenario will be reloaded and any modifications will be played with.
 +
** '''[scenario]''': Describes basic statistics of a previous scenario. See [[StatisticalScenarioWML]] for a description of [scenario]
 +
 
 +
 
 +
'''[snapshot]'''
 +
 
 +
The [snapshot] describes the current state of the game in an in-game save. It has the same format as the rest of the savefile and holds the map of the scenario. The snapshot is loaded when “Show replay” is not selected.
 +
 
 +
* '''playing_team''': the number of the team whose turn it is, starting with 0
 +
* '''turn_at''': The number of the current turn
 +
* '''map_data''': The data for the map. The mini-map generated by this data is displayed to the right
 +
 
 +
 
 +
'''[replay_start]'''
 +
 
 +
[replay_start] is a full snapshot of the start of the first turn of a scenario. It describes the position the player was in when the game started and is used as starting point for replays.
 +
 
 +
 
 +
'''[replay]'''
 +
 
 +
The [replay] contains everything that happened in the scenario since it started.
 +
 
 +
* '''[command]''': Describes one action. Syntax for [command] is described in [[ReplayWML]]
 +
 
 +
 
 +
'''[carryover_sides_start]'''
 +
 
 +
[carryover_sides_start] contains the carryover data from the previous scenario, like retained gold and units. It is also used to store in-game data required in the next level, such as variables, the random seed and menu items. [carryover_sides_start] retains the data throughout the scenario.
 +
 
 +
* '''random_calls''' and '''random_seed''': Used to determine and synchronize random events in the game
 +
* '''[side]''': Player information, retained gold, recruits and recalls for all sides in the game
 +
* '''[end_level_data]''': Contains the information how the carryover data should be used.
 +
* '''[variables]''': a list of the current values of all variables. The attribute variable_name=value means that the variable ''variable_name'' has the content ''value''. The tag [array_name] describes an array stored in the array ''array_name'' (which could describe a unit see [[SingleUnitWML]]). See also [[VariablesWML]]
 +
* '''[menu_item]''': Custom WML menu items
 +
 
 +
 
 +
'''[carryover_sides]'''
 +
 
 +
[carryover_sides] is a copy of the data in [carryover_sides_start]. Anything to be used in the new scenario is removed from [carryover_sides]. At the end of the scenario the carryover for the next scenario is added to what is left in [carryover_sides].
 +
 
 +
'''[scenario]'''
 +
 
 +
{{DevFeature1.13|0}} Expanded Start-of-scenario saves are almost the same as normal start-of-scenario saves, except that they also contain the start [scenario] so it doesn't need to be read from the game config.
 +
In most cases, this type of savegame is used internally, for example, at the beginning of a fresh networked mp game, where this host sends this type of savefile to the other clients, which is then loaded by them.
 +
 
 +
But in theory the game can also read an expanded start-of-scenario save from disk.
  
 
== See Also ==
 
== See Also ==

Latest revision as of 19:05, 4 September 2024

[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 format for Wesnoth savegames

A Wesnoth savegame is a file stored in ~saves/ (See "user data directory", PreprocessorRef). In order to view or modify these files, the option Compressed Saves (Advanced Preferences) must be set to "No". Also, since they are not config(.cfg) files the normal coloring will not be generated. To generate coloring, simply save the file as .cfg, then open it again.

There are 3 types of savegames: start-of-scenario, replay and in-game (including autosave and out-of-sync save). The information included in a save depends on its type.

Start-of-scenario Replay In-game
General info and statistics Yes Yes Yes
[snapshot] No No Yes
[replay] No Yes Yes
[replay_start] No Yes Yes
[carryover_sides] No Yes Yes
[carryover_sides_start] Yes Yes Yes

(Version 1.13.0 and later only) There are 4 types of savegames: start-of-scenario, expanded start-of-scenario, replay and in-game (including autosave and out-of-sync save). The information included in a save depends on its type.

Start-of-scenario Expanded Start-of-scenario Replay In-game
General info and statistics Yes Yes Yes Yes
[snapshot] No No No Yes
[replay] No No Yes Yes
[replay_start] No No Yes Yes
[carryover_sides] No No Yes Yes
[carryover_sides_start] Yes Yes No No
[scenario] No Yes No No

(Version 1.13.0 and later only) There are also 2 types of Server generated replays

Fresh game Start-of-scenario Reloaded game
General info and statistics Yes Yes Yes
[snapshot] No No Yes
[replay] Yes Yes Yes
[replay_start] No No Yes
[carryover_sides] No No Yes
[carryover_sides_start] Yes Yes No
[scenario] Yes Yes No


General info and statistics

Contains general information about the scenario, campaign and version of Battle for Wesnoth the savegame is from. This information is included in all savegames. Not all tags of this section are explained here.

  • version: The version of Wesnoth this game was saved by. If the savegame is from a different version of Wesnoth than the one currently running, the message "This save is from a different version of the game. Do you want to try to load it?" is displayed
  • campaign_type: Whether the scenario is a scenario or multiplayer.
  • campaign_define: When this replay is loaded, the symbol campaign_define will be stored. See also "#ifdef", PreprocessorRef
  • difficulty: The difficulty level of the savegame. Normal values are "EASY", "NORMAL", and "HARD".
  • label: heading of the save
  • next_scenario: Name of the next scenario in a campaign
  • scenario: Name of the current scenario
  • [multiplayer]: If the game is a multiplayer game, multiplayer information is included here
  • [statistics]: Describes previous scenarios
    • mid_scenario: If "false", the scenario will be reloaded and any modifications will be played with.
    • [scenario]: Describes basic statistics of a previous scenario. See StatisticalScenarioWML for a description of [scenario]


[snapshot]

The [snapshot] describes the current state of the game in an in-game save. It has the same format as the rest of the savefile and holds the map of the scenario. The snapshot is loaded when “Show replay” is not selected.

  • playing_team: the number of the team whose turn it is, starting with 0
  • turn_at: The number of the current turn
  • map_data: The data for the map. The mini-map generated by this data is displayed to the right


[replay_start]

[replay_start] is a full snapshot of the start of the first turn of a scenario. It describes the position the player was in when the game started and is used as starting point for replays.


[replay]

The [replay] contains everything that happened in the scenario since it started.

  • [command]: Describes one action. Syntax for [command] is described in ReplayWML


[carryover_sides_start]

[carryover_sides_start] contains the carryover data from the previous scenario, like retained gold and units. It is also used to store in-game data required in the next level, such as variables, the random seed and menu items. [carryover_sides_start] retains the data throughout the scenario.

  • random_calls and random_seed: Used to determine and synchronize random events in the game
  • [side]: Player information, retained gold, recruits and recalls for all sides in the game
  • [end_level_data]: Contains the information how the carryover data should be used.
  • [variables]: a list of the current values of all variables. The attribute variable_name=value means that the variable variable_name has the content value. The tag [array_name] describes an array stored in the array array_name (which could describe a unit see SingleUnitWML). See also VariablesWML
  • [menu_item]: Custom WML menu items


[carryover_sides]

[carryover_sides] is a copy of the data in [carryover_sides_start]. Anything to be used in the new scenario is removed from [carryover_sides]. At the end of the scenario the carryover for the next scenario is added to what is left in [carryover_sides].

[scenario]

(Version 1.13.0 and later only) Expanded Start-of-scenario saves are almost the same as normal start-of-scenario saves, except that they also contain the start [scenario] so it doesn't need to be read from the game config. In most cases, this type of savegame is used internally, for example, at the beginning of a fresh networked mp game, where this host sends this type of savefile to the other clients, which is then loaded by them.

But in theory the game can also read an expanded start-of-scenario save from disk.

See Also

Retrieved from "https://wiki.wesnoth.org/index.php?title=SavefileWML&oldid=73630"
This page was last edited on 4 September 2024, at 19:05.