Storage Module Usage
====================

The storage module contains several cmoponents that can be used
separately or in combination for the following tasks:

- Settings store that holds game settings persistently:
  (machine-specific, user-specific and achievements)

- A save slot manager through which a game can manage multiple
  player profiles in a very simple fashion

- Game state store that holds informations about the game's state
  and allows this to be saved

- Some serialization helpers including a tamper-detecting XML serializer



Usage: Game Saving
------------------

Step 2: State Class - Write class that holds the game state you wish to save

This class will store everything the game needs to know across scene changes. It
can also be saved into a file and loaded again at a later time to provide game
saving functionality.

It is possible (and encourages) to create sub-classes to structure the game state.
The game state root class that we will write here needs to implement the IGameState
interface (which is inteded to other modules to access common settings)

    /// <summary>Stores the current state of things in the doodle game</summary>
    public class DoodleGameState : IGameState {

      /// <summary>How much health the player has left</summary>
      public int PlayerHealth = 3;

      /// <summary>Date and time the player last played the game</summary>
      public DateTime LastPlayed;

      /// <summary>How long the player has played with this profile</summary>
      public TimeSpan PlayingTime;

      /// <summary>Last time the user played on this state (UTC time)</summary>
      DateTime IGameState.LastPlayed {
        get { return this.LastPlayed; }
        set { this.LastPlayed = value; }
      }

      /// <summary>For how long the user been playing this state in total</summary>
      TimeSpan IGameState.PlayingTime {
        get { return this.PlayingTime; }
        set { this.PlayingTime = value; }
      }

      /// <summary>How far along the game the state is</summary>
      float IGameState.Progress {
        get { return 0.0f; }
      }

    }

Step 2: Initialization - Write a game-specific adapter component

The settings and savegame stores need to be initialized exactly once during
your game's lifetime. Of course, we do not want to lose the ability to just
open any scene and play it in the editor, so to handle initialization, we
will write an adapter component that is specific to each game.

    /// <summary>Provides, saves and loads the current game state</summary>
    public class DoodleGameStateStore : ScriptComponent {

      /// <summary>Current game state that will persistent across sessions</summary>
      public DoodleGameState State {
        get { return this.gameStateStore.GameState.Access<DoodleGameState>(); }
      }

      /// <summary>Injects the instance's dependencies</summary>
      /// <param name="gameStateStore">Store holding the current game state</param>
      /// <remarks>
      ///   This method is called automatically by the services framework. Any parameters
      ///   it requires will be filled out by looking up the respective services and creating
      ///   them as needed.
      /// </remarks>
      protected void Inject(IPersistentGameStateStore gameStateStore) {
        this.gameStateStore = gameStateStore;

        if(!this.gameStateStore.IsInitialized) {
          this.gameStateStore.Initialize<DoodleGameState>();
        }
      }

      /// <summary>Holds the current game state and allows saving it</summary>
      private IPersistentGameStateStore gameStateStore;


    }


Step 3: Call Load() / Save() as needed

The persistent game state manager you obtain from the Inject() method above
(via the dependency injection service) offers methods like StartNewGame(),
LoadGame(), SaveGame() and DeleteGame().

Call these from your game's menu or in any other situation where the player
wants to begin a new game, load or save the game's state.


Step 4: Write a custom serializer (optional)

If you want to change the file format (for example, going binary instead of XML)
or tamper-protect your game's saves, you need to implement a custom serializer.

This can be very little code because you can just forward to the standard serializer
and add the things you want (i.e. delegates for reading and writing the checksum
from the state for the TamperDetectingSerializer instead).

Through custom serializers, it's also possible to change the file name of
the game state file, or to write additional files (i.e. index data so your
game can quickly load summary information about a saved game and display this
to the player).



Usage: Settings
---------------

Same as game saving, but use IPersistentSettingsStore