source/ps/SavedGame.h

   1 /* Copyright (C) 2017 Wildfire Games.
   2  * This file is part of 0 A.D.
   3  *
   4  * 0 A.D. is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation, either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * 0 A.D. is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with 0 A.D.  If not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 #ifndef INCLUDED_SAVEDGAME
  19 #define INCLUDED_SAVEDGAME
  20
  21 #include "scriptinterface/ScriptInterface.h"
  22 class CSimulation2;
  23 class CGUIManager;
  24
  25 /**
  26  * @file
  27  * Contains functions for managing saved game archives.
  28  *
  29  * A saved game is simply a zip archive with the extension '0adsave'
  30  * and containing two files:
  31  * <ul>
  32  *  <li>metadata.json - JSON data file containing the game metadata</li>
  33  *      <li>simulation.dat - the serialized simulation state data</li>
  34  * </ul>
  35  */
  36
  37 namespace SavedGames
  38 {
  39
  40 /**
  41  * Create new saved game archive with given name and simulation data
  42  *
  43  * @param name Name to save the game with
  44  * @param description A user-given description of the save
  45  * @param simulation
  46  * @param guiMetadataClone if not NULL, store some UI-related data with the saved game
  47  * @return INFO::OK if successfully saved, else an error Status
  48  */
  49 Status Save(const CStrW& name, const CStrW& description, CSimulation2& simulation, const shared_ptr<ScriptInterface::StructuredClone>& guiMetadataClone);
  50
  51 /**
  52  * Create new saved game archive with given prefix and simulation data
  53  *
  54  * @param prefix Create new numbered file starting with this prefix
  55  * @param description A user-given description of the save
  56  * @param simulation
  57  * @param guiMetadataClone if not NULL, store some UI-related data with the saved game
  58  * @return INFO::OK if successfully saved, else an error Status
  59  */
  60 Status SavePrefix(const CStrW& prefix, const CStrW& description, CSimulation2& simulation, const shared_ptr<ScriptInterface::StructuredClone>& guiMetadataClone);
  61
  62 /**
  63  * Load saved game archive with the given name
  64  *
  65  * @param name filename of saved game (without path or extension)
  66  * @param scriptInterface
  67  * @param[out] metadata object containing metadata associated with saved game,
  68  *      parsed from metadata.json inside the archive.
  69  * @param[out] savedState serialized simulation state stored as string of bytes,
  70  *      loaded from simulation.dat inside the archive.
  71  * @return INFO::OK if successfully loaded, else an error Status
  72  */
  73 Status Load(const std::wstring& name, const ScriptInterface& scriptInterface, JS::MutableHandleValue metadata, std::string& savedState);
  74
  75 /**
  76  * Get list of saved games for GUI script usage
  77  *
  78  * @param scriptInterface the ScriptInterface in which to create the return data.
  79  * @return array of objects containing saved game data
  80  */
  81 JS::Value GetSavedGames(const ScriptInterface& scriptInterface);
  82
  83 /**
  84  * Permanently deletes the saved game archive with the given name
  85  *
  86  * @param name filename of saved game (without path or extension)
  87  * @return true if deletion was successful, or false on error
  88  */
  89 bool DeleteSavedGame(const std::wstring& name);
  90
  91 /**
  92  * Gets info (version and mods loaded) on the running engine
  93  *
  94  * @param scriptInterface the ScriptInterface in which to create the return data.
  95  * @return list of objects containing saved game data
  96  */
  97 JS::Value GetEngineInfo(const ScriptInterface& scriptInterface);
  98
  99 }
 100
 101 #endif // INCLUDED_SAVEDGAME