Integrating with Windows Game Explorer

Microsoft Game Technology Group

December 2005

Updated: August 2006

Introduction

Microsoft Windows Vista improves the user experience of gaming on Windows by including Game Explorer. Game Explorer is exposed in the Windows Vista Start Menu as the Games folder and provides a central location for accessing games. This article outlines the process of registering a game with Game Explorer and parental controls.

Prerequisites

Before you can integrate a game into Game Explorer, you must create a game definition file (GDF). A GDF is an XML file that contains metadata describing the game. Microsoft provides a tool for authoring GDFs in the DirectX SDK, Game Definition File Editor, to make this creation process easier. This tool also helps you create localized versions of a GDF.

Once a GDF has been authored and localized, it must be encapsulated within a resource section of a binary file (either an executable or DLL), along with the game's thumbnail and icon. The GDF contains all the metadata assocatied with the game including the game's rating. Windows Vista parental controls use the game's rating to allow parents to control access to the game. The binary file which contains the GDF must be digitally signed with a valid Authenticode certificate; otherwise, Game Explorer and the parental control system will ignore the game's rating, because the rating information cannot be trusted without certification. For more details about signing code with Authenticode, see Authenticode Signing for Game Developers

Integration Process

Once the GDF and related files have been added to a binary resource, it is then possible to integrate the game with Game Explorer. It is strongly advised that games integrate with Game Explorer during the installation process. The outline to the integration process is as follows:

  1. Install ALL files to the user's hard drive. The next step activates parental controls and could potentially lock the user out of the installation directory.
  2. Create an instance to the IGameExplorer interface.
  3. Call the VerifyAccess method, of the IGameExplorer interface and pass it the path to the GDF.
  4. Call the AddGame method, of the IGameExplorer interface and pass it the path to the GDF, the path to the root installation directory, and a unique GUID called the game instance ID.
  5. Create shortcuts, which are Game Explorer tasks, by using the game instance ID. Game Explorer tasks are explained in the next section.

Game Explorer Tasks

Game Explorer tasks are what users see when they right-click on a game in Game Explorer. Tasks are simply shortcuts located in known folders. Tasks are divided into play tasks and support tasks. For example, if you want a shortcut that launches a game into a multiplayer mode, that is a play task. If you want a shortcut to a web site, that shortcut is a support task. Play tasks and support tasks are stored in directories with the corresponding names PlayTasks and SupportTasks. You are responsible for creating both the shortcuts and these directories.

In the following example layout of a task folder, the paths to the shortcuts begin with the path returned from SHGetFolderPath by passing it either CSIDL_COMMON_APPDATA or CSIDL_LOCAL_APPDATA; which should be passed depends on whether the game is being installed for all users or just the current user. Also, {game instance ID} is the GUID that is passed to the AddGame function.

The following are example shortcuts:

.\Microsoft\Windows\GameExplorer\{game instance ID}\PlayTasks\0\Play.lnk

.\Microsoft\Windows\GameExplorer\{game instance ID}\PlayTasks\1\Play Online.lnk

.\Microsoft\Windows\GameExplorer\{game instance ID}\SupportTasks\0\Developer's Website.lnk

Note    The location specified by these paths is relative to the location returned by SHGetFolderPath.

When tasks are shown, the name of the link is displayed to the user, with the exception of the first link in PlayTasks, which is always called Play. The tasks are displayed in ascending order by the numbered subdirectory of their link. More information about tasks can be found in the documentation for Game Explorer.

Removal Process

The process of removing a game from Game Explorer is easy, and you can do so by performing the following steps:

  1. Create an instance to the IGameExplorer interface.
  2. Call the RemoveGame method with the game instance ID that was used during the integration process.
  3. Delete the appropriate game files and task folders.

This process only removes one unique installation. If a game has been installed multiple times, this process must be repeated for each unique installation.

Integrating into an Installer

If possible, you should call the Game Explorer APIs during installation. GameuxInstallHelper is a sample DLL to help you in this process, and it and its source code are provided in the DirectX SDK. GameuxInstallHelper is designed to work with scripts for InstallShield and Wise Installation System, as well as MSI custom actions and custom installation tools. The functions exported by this DLL are the following:

GenerateGUID
Creates a unique game instance ID.
AddToGameExplorerW
Registers a game with Game Explorer, given a game instance ID and a path to the GDF binary.
AddToGameExplorerA
Registers a game with Game Explorer; ANSI version of AddToGameExplorerW.
RetrieveGUIDForApplicationW
Returns a game instance ID, given the path to a GDF binary that has already been registered.
RetrieveGUIDForApplicationA
Returns a game instance ID; ANSI version of RetrieveGUIDForApplicationW.
RemoveFromGameExplorer
Removes a game from registration with Game Explorer, given a game instance GUID.
CreateTaskW
Creates a task shortcut in the proper location, given a game instance ID.
CreateTaskA
Creates a task shortcut in the proper location; ANSI version of CreateTaskW.
RemoveTasks
Removes all of the tasks associated with a game instance ID.
SetupRichSavedGamesW
Creates the registry keys to enable rich saved games.
SetupRichSavedGamesA
Creates the registry keys to enable rich saved games; ANSI version of SetupRichSavedGamesW.
RemoveRichSavedGamesW
Removes the registry keys to enable rich saved games.
RemoveRichSavedGamesA
Removes the registry keys to enable rich saved games; ANSI version of RemoveRichSavedGamesW.
SetMSIGameExplorerProperties
Configures the CustomActionData properties for the actions of an MSI deferred custom installation. Usage of this function is described in detail below.
AddToGameExplorerUsingMSI
Adds a game to Game Explorer; for use during an MSI custom action installation.
RemoveFromGameExplorerUsingMSI
Removes a game from Game Explorer; for use during an MSI custom action installation.

Integrating into InstallScript

Calling Game Explorer APIs from InstallShield's InstallScript is made easy by using the DLL, GameuxInstallHelper, described earlier. The steps required to integrate with InstallShield are as follows:

  1. Open an InstallScript project in the InstallShield editor.
  2. Add GameuxInstallHelper.dll to the project as a support file.
    1. Under the Installation Designer tab, open the Behavior and Logic folder.
    2. Under Support Files/Billboards, open Advanced Files, then open Disk1, and right-click in File or press the INSERT key.
    3. Browse for GameuxInstallHelper.dll and add it to the project.
  3. In the InstallScript explorer, click the InstallScript file (usually setup.rul) that calls the DLL function.
  4. Paste this InstallScript into the file: 
    typedef GUID
begin
  LONG Data1;
  SHORT Data2;
  SHORT Data3;
  CHAR  Data4(8);
end;

prototype LONG GameuxInstallHelper.AddToGameExplorerW( WSTRING, WSTRING, NUMBER, GUID POINTER );
prototype LONG GameuxInstallHelper.RemoveFromGameExplorer( GUID POINTER );
prototype LONG GameuxInstallHelper.RetrieveGUIDForApplicationW( WSTRING, GUID POINTER );
prototype LONG GameuxInstallHelper.GenerateGUID( GUID POINTER );
prototype LONG GameuxInstallHelper.CreateTaskW( NUMBER, GUID POINTER, NUMBER, NUMBER, WSTRING, WSTRING, WSTRING );
prototype LONG GameuxInstallHelper.RemoveTasks( GUID POINTER );
prototype LONG GameuxInstallHelper.SetupRichSavedGamesW( WSTRING, WSTRING, WSTRING );
prototype LONG GameuxInstallHelper.RemoveRichSavedGamesW( WSTRING );

function OnEnd()
  
  WSTRING gdfbin[256];
  WSTRING path[256];
  NUMBER scope;       
  NUMBER supportTask;
  NUMBER playTask;
  GUID guid;
  GUID POINTER pGuid;

begin

  UseDLL( SUPPORTDIR ^ "GameuxInstallHelper.dll" );
  UseDLL( WINSYSDIR ^ "OLE32.dll" );
  
  path = TARGETDIR;
  gdfbin = path ^ "bin\\ExampleGame.exe";  // TODO: Change this to point to binary containing the GDF 
  pGuid = &guid;   
  playTask = 0;
  supportTask = 1;    

  if !MAINTENANCE then  
    if ALLUSERS == 1 then
      scope = 3;
    else
      scope = 2;
    endif;                                             
                 
    GameuxInstallHelper.GenerateGUID( pGuid );
    GameuxInstallHelper.AddToGameExplorerW( gdfbin, path, scope, pGuid );
    
    // TODO: Add/remove/change tasks 
    
    // Play tasks.  You can define up to 6
    GameuxInstallHelper.CreateTaskW( scope, pGuid, playTask, 0, "Play", gdfbin, "" );
    GameuxInstallHelper.CreateTaskW( scope, pGuid, playTask, 1, "Network Play", gdfbin, "-network" );
    GameuxInstallHelper.CreateTaskW( scope, pGuid, playTask, 2, "Safe Mode", gdfbin, "-safe" );
    
    // Support tasks.  You can define up to 5
    GameuxInstallHelper.CreateTaskW( scope, pGuid, supportTask, 0, "Support", "http://www.msn.com", "" );       
    
    // Setup rich save game support 
    // TODO: change the saved game file extension 
    GameuxInstallHelper.SetupRichSavedGamesW( ".ExampleSaveGame", gdfbin, "%1" );
  endif;
  
  if MAINTENANCE && UNINST != "" then
    GameuxInstallHelper.RetrieveGUIDForApplicationW( gdfbin, pGuid );
    GameuxInstallHelper.RemoveFromGameExplorer( pGuid );
    GameuxInstallHelper.RemoveTasks( pGuid );
    GameuxInstallHelper.RemoveRichSavedGamesW( ".ExampleSaveGame" );
  endif;
  
  UnUseDLL( SUPPORTDIR ^ "GameuxInstallHelper.dll" );
  UnUseDLL("OLE32.dll");
  
end;

Integrating into an MSI Package

Calling Game Explorer APIs from inside MSI custom actions is slightly different from the way that this is done with InstallShield. The required steps can be summarized by the following high-level description of the procedure:

  1. Add 1 property "RelativePathToGDF" (described later).
  2. After the CostFinalize action, call SetMSIGameExplorerProperties in an immediate custom action to set the appropriate MSI properties for the other custom actions.
  3. During installation after the InstallFiles action, call a deferred custom action that uses the GameuxInstallHelper function AddToGameExplorerUsingMSI.
  4. During removal after the InstallFiles action, call a deferred custom action that uses the GameuxInstallHelper function RemoveFromGameExplorerUsingMSI.
  5. During rollback, call a deferred custom action which also calls the GameuxInstallHelper function RemoveFromGameExplorerUsingMSI.

This procedure is described in detail in the following instructions, which provide the information for completing the procedure by using an MSI editor like Orca, which is found in the Platform SDK. Note that some MSI editors have wizards which simplify some of these configuration steps.

To configure an MSI package for integration with Game Explorer

  1. Open the MSI package in Orca.
  2. Add the row shown in the following table to the Binary table in the MSI package.
    Name Data
    GAMEUX file path to the DLL\GameuxInstallHelper.dll

    Note    This file will be embedded in the MSI package, so you must do this step every time you recompile GameuxInstallHelper.dll.

  3. Add the rows shown in the following table to the CustomAction table in the MSI package.
    Action Type Source Target
    SetMSIGameExplorerProperties 65 GAMEUX SetMSIGameExplorerProperties
    AddToGameExplorerUsingMSI 1089 GAMEUX AddToGameExplorerUsingMSI
    RemoveFromGameExplorerUsingMSI 1089 GAMEUX RemoveFromGameExplorerUsingMSI
    RollBackAddToGameExplorer 1345 GAMEUX RemoveFromGameExplorerUsingMSI
  4. Add the values shown for Action, Condition, and Sequence in the following table to the InstallExecuteSequence table in the MSI package.
    Action Condition Sequence Notes on Sequence Number
    SetMSIGameExplorerProperties 1015 This places the action soon after CostFinalize.
    AddToGameExplorerUsingMSI NOT Installed 4015 This places the action after InstallFiles.
    RollBackAddToGameExplorer NOT Installed 4014 This places the action directly before the custom action AddToGameExplorerUsingMSI, which indicates that this is its rollback action.
    RemoveFromGameExplorerUsingMSI Installed 4025 This places the action after InstallFiles.
  5. Add the row shown in the following table to the Property table in the MSI package.
    Property Value
    RelativePathToGDF relative file path\name of binary file that contains the GDF

    Note    The location specified by the path is relative to the location specified by the installation path. For example, bin\GDF.dll.

  6. Save the MSI package.

For more detailed information about MSI packages and Windows Installer, see Windows Installer on MSDN.

Summary

Game Explorer in Windows Vista provides an easy, customizable way to present your game to users of Windows Vista, but it also requires you to register the game with the system during the installation process. By using the sample code and the DLL described in this article, GameuxInstallerHelper, this registration process is simplified.