Getting Started With Game Explorer

Windows Vista Game Explorer provides game developers with a secure and attractive way to present their games to users in Windows Vista. This document details how to add a game to Game Explorer.

What is Game Explorer?

Windows Vista Game Explorer is a custom folder for the Windows Vista shell that provides a rich presence for games. It is accessed on the Start by clicking Games.

Game Explorer provides:

• Display of game title, description, version, release date, publisher, and developer information
• Display of general or region-specific game box art
• Display of minimum and recommended system performance ratings
• Display of game content ratings and descriptors
• Restriction of game play based on parental control settings
• Customizable context menus when a game is right-clicked
• Unique settings for multiple installations on the same system

Using Game Explorer

To enable your game to use Game Explorer, you must create the data files that Game Explorer relies on, and add your game to Game Explorer.

• Creating Game Explorer Data Files
• Adding a Game to Game Explorer
• Enabling Game Explorer on a Domain

Creating Game Explorer Data Files

The first part to adding a game to Game Explorer is to create and properly include a set of data that is consumed by Game Explorer. Doing this consists of the following steps.

Step 1. Create GDFs

Game Explorer displays a variety of data about each game. This data is stored in an XML-based document called a game definition file (GDF). For your information to be shown, you must author at least one GDF; if you want your game information to be localized for different world regions, you must author several GDFs, one for each region.

The GDF format is defined by a schema, which requires only a minimal set of information; many of the fields are optional. In creating your GDF, you can choose the level of detail that you want to supply to Game Explorer.

To see examples of minimal and full GDF files, and to understand the schema for GDF files, see The Game-Definition-File (GDF) Schema.

Step 2. Create Bitmaps

Game Explorer displays artwork for every game that provides it. The artwork provided is shown in a small format in the list of games, and in a large format when a game is selected by the user. Create an image file that will represent your game in Game Explorer.

The image should be in PNG format, as this allows for transparency features to give your artwork a clean look in the Game Explorer. Other formats are also available. For a list of formats, see GDF Delivery and Localization

Step 3. Embed GDFs and Bitmaps

The GDF files and bitmap files that are used by Game Explorer cannot be independent files that are simply installed in a game's directory along with the rest of the game files. They must be embedded as resources, either into an executable file or a DLL.

The Game Explorer header (GameUx.h) contains defined constants that you must use in the resource script to identify your GDF and bitmap file so that Game Explorer can find them. By separating the resource script into sections with #ifdef for multiple languages, you can instruct Game Explorer to search for localized versions of GDF files and bitmaps.

For more information, see GDF Delivery and Localization.

Adding a Game to Game Explorer

The second step to adding a game to Game Explorer is performed by the game's installer. The installer's code must identify the location of the game data for Game Explorer. Because Game Explorer is only available on Windows Vista, a different set of steps must be taken for an installation on a computer running Windows XP than on one running Windows Vista. Games that do not use an installer can perform these tasks at launch time, if necessary.

• Adding a Game to Windows Vista
• Adding the Game to Windows XP

Adding a Game to Windows Vista

If a game is installed on Windows Vista, it can be added to Game Explorer, and this is the most straightforward scenario.

Step 1. Install Game Files

The first step in adding your game to the Game Explorer is to have your game files installed on the hard drive. It is important that all game files be installed by this step; once the game is added to Game Explorer in step 4, the parental controls of Windows Family Safety might prevent your installation process from accessing the game's base directory to add or change files.

Step 2. Create IGameExplorer COM Object

The next step is to create the IGameExplorer COM object that you will use to add your game information to the Game Explorer.

Step 3. Call IGameExplorer::VerifyAccess

To check whether the game has permission to run on the current user's account, call VerifyAccess. Note that doing so also adds the game to the "Parental Controls Activity Viewer" log. Additionally, you must call this function prior to logging into the parental controls activity viewer. The VerifyAccess method takes as a parameter the path to your game's GDF. It checks parental control rating in the GDF against the current user's parental control settings and determines whether the current user has the necessary permission to run the game.

You might choose to inform the user of their lack of permission to run the game, since if VerifyAccess returns FALSE, the user will not be allowed to run the game.

Step 4. Call IGameExplorer::AddGame

To identify your game to Game Explorer, you must call AddGame with the path to your GDF resource, the path to your base installation, the installation scope, and optionally, an InstanceID (a GUID). You can either provide an InstanceID for the pguidInstanceID parameter using a GUID that you generate, or, by setting pguidInstanceID to GUID_NULL, one will be generated for you. The InstanceID uniquely identifies the instance of your game added to the Game Explorer, and you must persist it in the next step.

Note that after calling AddGame, restriction by parental control settings might prevent the game's installation directory from being accessed by the current user.

Step 5. Make the Game InstanceID Persistent

Store the InstanceID that you retrieved from or passed into AddGame, using either a file or the registry. Alternatively you can look up your InstanceID at runtime using WMI. See the various samples for more information on how to do this.

Step 6. Create Game Task Folders

Tasks are the actions that a user can perform on your game in Game Explorer. Actions such as playing the game, updating the game, or visiting the game's website are examples of tasks. You must create a directory structure that represents the tasks that you wish to support for your game, even if you only want to support the default task, which runs when the user double-clicks on the game in Game Explorer. See Game Explorer Tasks.

Adding the Game to Windows XP

You can install your game on a computer running Windows XP and store extra information so that your game will show up in Game Explorer if the user upgrades the system to Windows Vista.

Step 1. Install Game Files

As in the Windows Vista scenario, the first step will be to install all of your game files to the user's system.

Step 2. Generate Your Own InstanceID

Because the Game Explorer APIs are not available in Windows XP, the system cannot generate an InstanceID for your game. Therefore, you must create your own InstanceID, which you should persist in a file or the registry.

Step 3. Create Game Task Folders

As in the Windows Vista scenario, you can prepare tasks - commonly-used actions - for your user. Because the user is currently running Windows XP, the tasks will not be available for use immediately, but they will be automatically added to the game in the Game Explorer when the user upgrades to Windows Vista. See Game Explorer Tasks as well as Supporting an Upgrade from Windows XP to Windows Vista.

Step 4. Install Registry Values

So that Windows Vista will add your game automatically upon installation of the operating system, you must create some values in the registry; for more information, see Creating Custom Registry Values.

Enabling Game Explorer on a Domain

To use parental controls on a Windows Vista Ultimate machine joined to a domain, you must change a group policy setting to make parental controls visible:

1. Run gpedit.msc
2. Navigate to Local Computer Policy | Computer Configuration | Administrative Templates | Windows Components | Parental Controls.
3. Set "Parental Controls control panel visible on a Domain" to enabled.
4. Log off and parental controls will be visible.

Related Topics

The Game-Definition-File (GDF) Schema

The topics provided here provide a detailed explanation of the XML-based GDF schema and how to best use the fields to represent your game.

Game Explorer Tasks

The topics provided here provide a detailed explanation of the Game Explorer task system, including how you can create your own custom tasks.

Game Definition File Editor

The topics provided here provide a detailed explanation of the Game Definition File Editor, which is a graphical utility designed for creating localized game definition files (GDFs). as well as the necessary resource compiler scripts to compile game-definition files.