Windows Game Explorer Integration 

Windows Game Explorer Integration

Microsoft Corporation

December 2005
Updated: April 2006

Introduction

Windows Vista improves the gaming experience on Windows by including a Game Explorer. The Game Explorer is a located right off the Start menu and provides a central location for installed games. This article outlines the process registering a game with the Game Explorer and parental controls.

Prerequisites

Before a developer can integrate a game with the Game Explorer the developer needs to create a Game Definition File (GDF). A GDF file is an XML file that contains metadata describing the game. Microsoft provides a GDF authoring tool in the DirectX SDK called the 'Game Definition File Editor' to help make this creation process easier. This tool also helps create localized versions of the GDF.

Once the GDF has been authored and localized, the GDF along with the game's thumbnail and icon need to be encapsulated within a resource section of a binary (either an executable or DLL). In order for Game Explorer to use the game's rating, this binary must be digitally signed with a valid Authenticode certificate otherwise the Game Explorer and the parental controls system will simply not use the game's rating as it can be trivially edited. For more details about Authenticode signing, 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 the Game Explorer. It is strongly advised that the integration with the Game Explorer occurs 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 the install directory.
  2. Create an instance to the IGameExplorer interface.
  3. Call the VerifyAccess method, of the IGameExplorer interface, with the path to the GDF.
  4. Call the AddGame method, of the IGameExplorer interface, with the path to the GDF, the path to the root installation directory, and a unique GUID called the GameInstanceID.
  5. Create shortcuts which are Game Explorer Tasks using the GameInstanceID GUID. Game Explorer Tasks are explained in the next section.

Game Explorer Tasks

Game Explorer Tasks are what the user sees when they right click on a game in the Game Explorer. They are simply shortcuts located in known folders. Tasks are divided into PlayTasks and SupportTasks. For example, if a developer wanted a shortcut that would launch a game into a multiplayer mode that would go under PlayTasks. If they wanted a shortcut to a developer's or publisher's website that shortcut would go under SupportTasks. The developer is responsible for creating the directories and the shortcuts in those directories.

The following is an example of a Task Folder layout:

CSIDL_COMMON_APPDATA\Microsoft\Windows\GameExplorer\{GameInstanceID GUID}\PlayTasks\0\Play.lnk

CSIDL_COMMON_APPDATA\Microsoft\Windows\GameExplorer\{GameInstanceID GUID}\PlayTasks\1\Play Online.lnk

CSIDL_COMMON_APPDATA\Microsoft\Windows\GameExplorer\{GameInstanceID GUID}\SupportTasks\0\Developer's Website.lnk

The links will start off with either CSIDL_COMMON_APPDATA or CSIDL_LOCAL_APPDATA. The difference between them is whether the game is being installed for all users or just the current user. In the above example {GameInstanceID GUID} would be the GUID that is passed into the AddGame function. When tasks are shown, the name of the link is displayed to the user with the exception of the first link in the PlayTasks which is always called 'Play'. The tasks will be displayed in ascending order by numbered subdirectory. More details about tasks can be found in the Game Explorer documentation.

Removal Process

The process of removing a game from the Game Explorer is easy:

  1. Create an instance to the IGameExplorer interface and call the RemoveGame method with the GameInstanceID GUID that was used during the integration process
  2. 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 will have to 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 is provided with source in the DirectX SDK. This DLL is designed to work with InstallShield script, Wise script, MSI custom actions, or a custom installer. The exported DLL functions are:

  • GenerateGUID - Creates a unique game instance GUID
  • AddToGameExplorerW - Given a game instance GUID and path to GDF binary, registers game with Game Explorer
  • AddToGameExplorerA - ANSI version of AddToGameExplorerW
  • RetrieveGUIDForApplicationW - Given a path to a GDF binary that has already been registered, returns a game instance GUID
  • RetrieveGUIDForApplicationA - ANSI version of RetrieveGUIDForApplicationW
  • RemoveFromGameExplorer - Given a game instance GUID, unregisters a game from Game Explorer
  • CreateTaskW - Given a a game instance GUID, creates a task shortcut in the proper location
  • CreateTaskA - ANSI version of CreateTaskW
  • RemoveTasks - This removes all the tasks associated with a game instance GUID
  • SetMSIGameExplorerProperties - For use during an MSI custom action install. This sets up the CustomActionData properties for the deferred custom actions. Usage of this function is described in detail below.
  • AddToGameExplorerUsingMSI - For use during an MSI custom action install. This adds the game to the Game Explorer
  • RemoveFromGameExplorerUsingMSI - For use during an MSI custom action install. This removes the game to the Game Explorer

Integrating into an InstallScript

Calling the Game Explorer APIs in InstallShield's InstallScript is easy using the GameuxInstallHelper DLL described above. The steps required to integrate are as follows:

  1. Open an InstallScript project in the InstallShield editor.
  2. Add the GameuxInstallHelper.dll to the project as a support file.
    1. Under 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 it to the project.
  3. In the InstallScript explorer, click the InstallScript file (usually setup.rul) that will call 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 );

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", "https://www.msn.com", "" );       

endif;

if MAINTENANCE && UNINST != "" then GameuxInstallHelper.RetrieveGUIDForApplicationW( gdfbin, pGuid ); GameuxInstallHelper.RemoveFromGameExplorer( pGuid ); GameuxInstallHelper.RemoveTasks( pGuid ); endif;

UnUseDLL( SUPPORTDIR ^ "GameuxInstallHelper.dll" ); UnUseDLL("OLE32.dll");

end;

Integrating into an MSI package

Calling the Game Explorer APIs inside MSI custom actions is slightly different. At the high level, these steps have to be done and will be explained in detail below:

  • Add 1 property "RelativePathToGDF" as described below.
  • After the CostFinalize action, call "SetMSIGameExplorerProperties" in an immediate custom action to set the appropriate MSI properties for the other custom actions.
  • During install after the InstallFiles action, call a deferred custom action that uses the GameuxInstallHelper's "AddToGameExplorerUsingMSI" function.
  • During uninstall after the InstallFiles action, call a deferred custom action that uses the GameuxInstallHelper's "RemoveFromGameExplorerUsingMSI" function.
  • During rollback, call a deferred custom action which also calls the GameuxInstallHelper's "RemoveFromGameExplorerUsingMSI" function.

The following is the steps need to do this using an MSI editor such as Orca found in the Platform SDK. Note that some editors have use wizards which simplify some of these steps:

  1. Open the MSI package in Orca
  2. Add the following to the Binary table:
  3. Add the following to CustomAction table:
  4. Add the following to the InstallExecuteSequence table
  5. Add the following to the Property table:

For more detailed information on how MSI works, see MSI documentation at: Windows Installer

Summary

The Windows Vista Game Explorer provides an easy, customizable way to present your game to users of Windows Vista but requires the developer to add the game to the system during the install process. Using the sample code and GameuxInstallerHelper DLL described in this article simplifies this process.