Back To GameSave.Info

Now hold up! You don't have to follow the directions on this page to get games added to GameSave.Info! Just use the Analyzer program included with MASGAU to send me a report on a game (it even has a button to automatically e-mail it for you!), and I'll add it for you! But, if you really want to understand how GameSave.Info and MASGAU sources their game data, feel free to read on!

  1. Introduction
  2. GameSave.Info uses an XML file checked into Github to describe where each game keeps its settings and saves. As you may or may not know, an XML file is little more than a specially typed text file, and can be created in programs as simple as notepad. All you do is fire up your favorite text editor and type the correct lines. Here's an excerpt from the games.xml file:

    <game name="DeusEx">
        <title>Deus Ex</title>
        <version os="PS2" region="USA">
          <title>Deus Ex: The Conspiracy</title>
          <ps_code prefix="SLUS" suffix="20111"/>
          <contributor>GameSave.Info</contributor>
        </version>
        <version os="Windows">
          <locations>
            <path ev="installlocation" path="DeusEx"/>
            <path ev="installlocation" path="GOG.com\Deus Ex"/>
            <path ev="steamcommon" path="deus ex"/>
            <registry root="local_machine" key="SOFTWARE\GOG.com\GOGDEUSX" value="PATH"/>
            <registry root="local_machine" key="SOFTWARE\Unreal Technology\Installed Apps\Deus Ex" value="Folder"/>
            <shortcut ev="startmenu" path="Programs\Deus Ex\Play Deus Ex.lnk" detract="System"/>
            <shortcut ev="startmenu" path="Programs\GOG.com\Deus Ex GOTY\Deus Ex GOTY.lnk" detract="System"/>
          </locations>
          <files>
            <include path="Save"/>
          </files>
          <files type="Settings">
            <include path="System" filename="*.ini"/>
          </files>
          <linkable path="Save"/>
          <identifier path="Save"/>
          <contributor>GameSave.Info</contributor>
        </version>
        <comment>The best game EVER!</comment>
    </game>

    This looks more intimidating than it is. Let's go into it line-by-line, but first some terms:

    <game name="DeusEx">
    Element or Tag
    That little bit of code is an element. Elements are surrounded by < and >.
    Attribute
    The word "name" in the above is an attribute. It's like a property of an element.

    NOTE: IN PATHS AND FILENAMES LEAVE OFF ALL LEADING AND TRAILING SLASHES ( \ AND / )

    ANOTHER NOTE: There is a schema file on GitHub. If you know what that means, use it.

  3. Game Tag
  4. <game name="DeusEx">

    The main purpose of this tag is to provide a unique internal name for the game. No spaces, and no symbols. Use CamelCase for legibility. Always use numbers instead of roman numerals, for sorting purposes. All versions of a game go under the same game tag. In this case, there is a version for Window and a version for PS2, but we'll talk about that more later.

    There are actually several variations on this tag, and you should try to use the one appropriate for your entry:

    <expansion name="MechWarrior4BlackKnight" for="MechWarrior4Vengeance">

    Use this if the entry is for an expansion pack, add-on or DLC for another game. In this example, Mechwarrior 4: Black Knight is an expansion for MechWarrior 4: Vengeance. The "for" attribute is required for an expansion, and MUST reference another game in the XML file. "Stand-alone expansions" do NOT get to be marked as an expansion. The term is an oxymoron, and makes no sense.

    <mod name="NamelessMod" for="DeusEx">

    Use this if the entry is for an MOD for another game. In this example, The Nameless Mod is a MOD for Deus Ex. The "for" attribute is required for a MOD, and MUST reference another game in the XML file.

    <system name="GamesForWindows">

    Use this when describing system data.

    There is a completely optional "follows" attribute that can be added to any of these variations:

    <game name="DeusExInvisibleWar" follows="DeusEx">

    It basically just indicates that the entry is somehow a follow-up (or sequel) to the indicated other entry. It's not parsed or used anywhere yet, but one day maybe.

    <game name="DeprecatedGame" deprecated="true">

    If a game is marked as deprecated, it means that the information provided is no longer considered correct. It's kept only for posterity and backwards-compatability.

    Obviously your closing tag should match your opening tag. Other than this, the contained tags are all the same.

  5. Game Title
  6. <title>Deus Ex</title>

    Between the two title tags you just type up the name of the game. This should be the name that was first attached to a game when it was release, other names would be delegated to version titles, which we will talk about later. Try to include the entire name, no reason to skimp on length. It might be tempting to shorten Penny Arcade Adventures: On The Rain Slick Precipice Of Darkness Chapter One to Penny Arcade Adventures 1, but resist it.

  7. Game Version
  8. <version os="Windows">

    The version tag is used to specify the versions of the game the contained saves are compatible with. In this case, it's compatible with Windows. This does NOT mean this save will only work on Windows, only that it's only for the Windows version of the game. This save would also be compatible with Linux if you have Deus Ex installed under WINE. The reason it is organized like this is because GameSave.Info also doubles as the data source for the game save backup program MASGAU.

    There are 5 attributes that allow us to describe a unique game save version:

    Attribute -> os platform region media release
    Description -> The operating system the save is compatible with The technology platform the save is compatible with The region of the world the save is for The delivery medium of the game version that the save is compatible with The release of the game the save is compatible with
    Possible Values -> Android
    DOS
    Linux
    OSX
    PS1
    PS2
    PS3
    PSP
    Windows
    WindowsVista
    WindowsXP
    Flash
    RenPy
    ScummVM
    SteamCloud
    UbisoftSaveStorage
    Any 3-letter ISO 3166-1 country code, or any of these two-letter continent codes:

    AF - Africa
    AS - Asia
    EU - Europe
    NA - North America
    SA - South America
    OC - Oceania
    (Antarctica has its own country code, so I won't support its continent code)
    CD
    Download
    Floppy
    GoG
    Steam
    This is freeform, can be anything at all. Some examples:

    CollectorsEdition
    TitaniumEdition
    Gold
    HD
    Remastered
    GOTY

    If a save is compatible with more than one thing in any of these categories, just don't specify the attribute. Try to keep the version specification as general as possible, while simultaneously making sure that a save would not accidentally get labelled as belonging to the wrong version of the game.

    <version os="Windows" media="CD" release="TitaniumEdition" region="USA">

    This example states that the contained saves are only compatible with the Windows version of the Titanium Edition of the game that was released on CD in the USA. This example is fake, I have yet to encounter saves that had such specific requirements.

    <version media="Steam">

    An important distinction should be made between a version for Steam and a version specifically for Steam Cloud data. The above is for the former, and the below for the latter.

    <version platform="SteamCloud">

    You could also specify media="Steam" on this, and it would be accurate but since SteamCloud automatically imples Steam, it's not necessary.

    My policy right now on DOS games is to label it as DOS if the save produced is only compatible with the DOS version of the game. If there exists a Windows version of a DOS game, and the saves are compatible with both, then both of the games' information would be combined into one Windows profile, such as with Master Of Orion 2 or Descent II.

    If you omit these attributes, then it is saying that the saves described are compatible with all versions of the game. This is pretty rare, but these games do exist. One example is fs2_open:

      <game name="fs2_open">
        <title>fs2_open</title>
        <version>      <locations>
            <path ev="installlocation" path="fs2_open"/>
            <parent name="FreeSpace2" os="Windows"/>
          </locations>
          <files>
            <include path="data\players"/>
          </files>
          <identifier filename="fs2_open*"/>
          <comment>Doesn't have a default install folder, so might require an Alt. Install Path.</comment>
          <contributor>GameSave.Info</contributor>
        </version>
      </game>

    If a game's saves were to work across just Linux and Windows, I would also not add a platform attribute, even if there was a Mac version with incompatible saves. By adding an additional Mac-specific version we would be declaring such an incompatibility.

    You can specify more than one version of a game within the same game tag:

     <game name="MechWarrior2">
        <title>MechWarrior 2: 31st Century Combat</title>
        <version os="Windows">      <locations>
            <path ev="installlocation" path="Activision\BattlePack\MW2"/>
            <shortcut ev="startmenu" path="Programs\BattlePack\MechWarrior 2\MechWarrior 2 Uninstall.lnk"/>
          </locations>
          <files type="Mechs">
            <include path="mek"/>
          </files>
          <files>
            <include filename="userstar.bwd"/>
          </files>
          <files type="Settings">
            <include filename="MW2PRM.CFG"/>
            <include filename="MW2REG.CFG"/>
          </files>
          <contributor>GameSave.Info</contributor>
        </version>
        <version os="Windows" release="TitaniumEdition">      <title>MechWarrior 2: 31st Century Combat: Titanium Edition</title>
          <locations>
            <path ev="installlocation" path="Activision\Titanium\Mechwarrior2"/>
            <path ev="altsavepaths" path="MechVM\games\mw2-31stcc-tt"/>
            <registry root="local_machine" key="SOFTWARE\Activision\Activenet\Applications\1020.2.1" value="Cwd"/>
            <shortcut ev="startmenu" path="Programs\Titanium\Mechwarrior2\Play MechWarrior2.lnk" detract="splash"/>
          </locations>
          <files type="Mechs">
            <include path="mek"/>
          </files>
          <files>
            <include filename="userstar.bwd"/>
          </files>
          <files type="Settings">
            <include filename="MW2PRM.CFG"/>
            <include filename="MW2REG.CFG"/>
          </files>
          <contributor>GameSave.Info</contributor>
        </version>
      </game>

    As you can see we only specify a version title when that version has a title different than the main one specified under the game tag.

    <version os="Windows" virtualstore="ignore" detect="required">

    There are two additional attributes demonstrated here:

    <version deprecated="true">

    If a version is marked as deprecated, it means that the information provided is no longer considered correct. It's kept only for posterity and backwards-compatability.

  9. Locations
  10. Games can keep their saves anywhere, so here we try to provide as many ways as possible of finding them. These locations are not the exact locations of the saves, but are instead roots used as the first step to find the saves. Why do we do it like this? Here's why:

    These are some possible save locations for Deus Ex: See how they're all different, but all end with the same Save folder?
    We can be certain that the Save folder is always used, no matter the location,
    and just specify the part of the path that we can't predict:
    C:\DeusEx\Save\ C:\DeusEx\
    C:\Program Files\GOG.com\Deus Ex\Save\ C:\Program Files\GOG.com\Deus Ex\
    C:\Program Files\Steam\steamapps\common\deus ex\Save\ C:\Program Files\Steam\steamapps\common\deus ex\

    The main point here is to not store the same information (the Save folder) more than once. This has space saving advantages, btu it also allows us to re-use the same location to specify Settings, Replays, Screenshots, or anything else that might happen to be there. We must be mindful to include enough of the root path that we can't mistake one game's paths for another. We have a few ways of finding these locations:

    1. Location Using A Path
    2. <path ev="installlocation" path="DeusEx"/>

      The path tag lets us specify an actual folder name, but sitll allows us to do so in a format that can adjust automatically for any system. This is attained via environment variables. The environment variable will be replaced with whatever the appropriate path from the system is, and prepended onto the provided path.

      The environment variables available for use:
      allusersprofile
      Warning: include_once(gamedata/Location.php): failed to open stream: No such file or directory in /var/www/gsi/xml_format.php on line 39

      Warning: include_once(): Failed opening 'gamedata/Location.php' for inclusion (include_path='.:/usr/share/php:/usr/share/pear') in /var/www/gsi/xml_format.php on line 39

      Warning: include_once(gamedata/GameVersion.php): failed to open stream: No such file or directory in /var/www/gsi/xml_format.php on line 40

      Warning: include_once(): Failed opening 'gamedata/GameVersion.php' for inclusion (include_path='.:/usr/share/php:/usr/share/pear') in /var/www/gsi/xml_format.php on line 40

      Fatal error: Class 'Location' not found in /var/www/gsi/xml_format.php on line 41