source/ps/SavedGame.h

   1 /* Copyright (C) 2021 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 "ps/CStr.h"
  22 #include "scriptinterface/StructuredClone.h"
  23
  24 class CSimulation2;
  25
  26 /**
  27  * @file
  28  * Contains functions for managing saved game archives.
  29  *
  30  * A saved game is simply a zip archive with the extension '0adsave'
  31  * and containing two files:
  32  * <ul>
  33  *  <li>metadata.json - JSON data file containing the game metadata</li>
  34  *      <li>simulation.dat - the serialized simulation state data</li>
  35  * </ul>
  36  */
  37
  38 namespace SavedGames
  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 Script::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 Script::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 #endif // INCLUDED_SAVEDGAME