Rich Saved Games (Vista Only)

Article
09/10/2011

Description

Windows Vista enables game developers to expose metadata and thumbnails to Games Explorer and Desktop Search through a shell handler, which processes saved game files and extracts their metadata. Windows Vista is required to extract metadata from rich saved games; however, on Windows XP you can enable part of the functionality by creating a saved game file association.

Note

This feature is not supported on Windows 7.

How to Support Rich Saved Games

The steps to support rich saved games are as follows:

Choose a unique file extension for your saved games, such as .MicrosoftHeartsSaved, to avoid collisions with other games. Avoid using extensions that are commonly used for saved game files, like .sav.
Modify your setup program to create a file association with your saved game files so that the game launches and loads the saved game when a user double-clicks on a saved game file. Details about this are found later in this topic.
Modify your setup program to register the saved game extension with Windows Vista's rich saved games property handler so that the saved game metadata can be extracted. This should be done during installation while the setup has administrative rights. Details about this are found later in this topic.
Modify your game to write saved game files that begin with the header described later in this topic. This allows metadata to be extracted by the property handler.
Modify your game to support loading a saved game from the command line if it doesn't already. This is needed for the file association to work properly.
Include the path of the saved games folder in the game's GDF file so that Games Explorer can show the folder of your saved games. For more information about the path of saved games, see The Game-Definition-File (GDF) Schema .

Creating a File Association for Your Saved Game File Extension

After you've selected a unique file extension for your saved games, you must create an association for that file extension. The file association allows the user to double-click on a saved game file and have the game automatically launch and load the saved game. To do this, you need to add some values to the registry, which requires administrative privileges. Your setup program will typically have administrative privileges, so installation is a good time to modify the registry.

The following is a sample registry entry for a saved game created by ExampleGame.exe, with a file extension of .ExampleGameSaved and a ProgID of ExampleGameSavedFileType:

[HKEY_CLASSES_ROOT\.ExampleGameSaved]
(Default)="ExampleGameSavedFileType"

[HKEY_CLASSES_ROOT\ExampleGameSavedFileType\Shell\Open\Command]
(Default)=""%ProgramFiles%\ExampleGame.exe" "%1""

Windows Vista Metadata Extraction for Saved Games

To enable Windows Vista to extract and display metadata from your saved games, you simply have to create a few registry keys and follow the saved game header guidelines described later in this topic.

The following is a sample registry entry for a saved game created by ExampleGame.exe, with a file extension of .ExampleGameSaved and a ProgID of ExampleGameSavedFileType:

[HKEY_CLASSES_ROOT\ExampleGameSavedFileType]
PreviewTitle="prop:System.Game.RichSaveName;System.Game.RichApplicationName"
PreviewDetails="prop:System.Game.RichLevel;System.DateChanged;System.Game.RichComment;System.DisplayName;System.DisplayType"

[HKEY_CLASSES_ROOT\.ExampleGameSaved\ShellEx\{BB2E617C-0920-11D1-9A0B-00C04FC2D6C1}]
(Default)="{4E5BFBF8-F59A-4E87-9805-1F9B42CC254A}"

[HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\PropertySystem\PropertyHandlers\.ExampleGameSaved]
(Default)="{ECDD6472-2B9B-4B4B-AE36-F316DF3C8D60}"

The DirectX SDK sample called GameuxInstallHelper contains example code that demonstrates how to create these registry keys. The sample is designed to work with InstallShield script, Wise script, MSI custom actions, or a custom installer.

Saved Game Header

In order for metadata to be extracted by the shell handler, the saved game must be written using the following header:

#define RM_MAXLENGTH    1024
#define RM_MAGICNUMBER  'HMGR'

#pragma pack(push)
#pragma pack(1)
typedef struct _RICH_GAME_MEDIA_HEADER
{
    DWORD       dwMagicNumber;
    DWORD       dwHeaderVersion;
    DWORD       dwHeaderSize;
    LARGE_INTEGER liThumbnailOffset;
    DWORD       dwThumbnailSize;
    GUID        guidGameId;
    WCHAR       szGameName[RM_MAXLENGTH];
    WCHAR       szSaveName[RM_MAXLENGTH];
    WCHAR       szLevelName[RM_MAXLENGTH];
    WCHAR       szComments[RM_MAXLENGTH];
} RICH_GAME_MEDIA_HEADER;
#pragma pack(pop)

The following table describes the fields in the header.

TYPE	DATA	DESCRIPTION
DWORD	dwMagicNumber	Must be 'HMGR'. This is used to recognize the header file format.
DWORD	dwHeaderVersion	Version of this header. This must be 1 to use this header.
DWORD	dwHeaderSize	Size of this header in bytes which is sizeof(RICH_GAME_MEDIA_HEADER).
LARGE_INTEGER	liThumbnailOffset	Offset to where the thumbnail starts relative from the end of the header. Thumbnails can be of any GDI+ type. Thumbnails should be in PNG or BMP format and no greater than 256×256 in size.
DWORD	dwThumbnailSize	Size of the thumbnail in bytes.
GUID	guidGameId	GUID of the game as used in the GDF file.
WCHAR[RM_MAXLENGTH]	szGameName	String name of the game. This text will be displayed and will be searchable.
WCHAR[RM_MAXLENGTH]	szSaveName	String description of the saved game. This text will be displayed and will be searchable.
WCHAR[RM_MAXLENGTH]	szLevelName	String description of the level. This can be an empty string. This text will be displayed and will be searchable
WCHAR[RM_MAXLENGTH]	szComments	String for comments about the saved game. This can be an empty string. This text will be displayed and will be searchable.
End of Header
BYTE*	Game-specific data area until the end of file	This is the actual saved game data. There are no requirements for this format.

A sample supplied in the DirectX SDK called GameuxInstallHelper contains an example in source code of how to create a saved game with this header.