Getting Started With The Game Explorer 

Getting Started With The Game Explorer

Note    This documentation is preliminary and is subject to change.

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

What is the Game Explorer?

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

The Game Explorer provides:

• Display of game title, description, version, release date, publisher, and developer information
• Display of general or region-specific "thumbnail" game box art image
• 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 on
• Unique settings for multiple installations on the same system

How To Add Your Game

There are two parts to adding your game to the Game Explorer: Creating data files that Game Explorer will consume, and adding your game to the Game Explorer.

Create Data Files That Game Explorer Will Consume

The first step is creating and properly including a set of data that is consumed by the Game Explorer.

Step 1. Create GDFs

The Game Explorer displays a variety of data about each game. This data is stored in an XML-based document called a Game Definition File, or GDF. In order for your information to be shown, you must author at least one of these GDF documents. If you want your game information to be localized for different world regions, you must author several of these 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 you want to supply to the 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

The 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 the 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 used by Game Explorer cannot be independent files that are simply installed into your game 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 file and bitmap file so that the Game Explorer can find them. By separating the resource script into #ifdef sections 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.

Add The Game To Game Explorer From The Game Installer

The second step is run in your game installation code. Your code must identify the location of your game data to the Game Explorer. Because the Game Explorer is only available in Windows Vista, a different set of steps must be taken for an installation on a Windows XP system than on a Windows Vista system. Games that do not use an installer can perform these tasks at launch time if necessary.

Adding The Game to Windows Vista

Installing on Windows Vista, you can add your game to the Game Explorer. 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 the Game Explorer in step 4, Parental Controls may prevent your install process from accessing the game's base install 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

An optional step is to call VerifyAccess to check if the game has permission to run on the current user account. VerifyAccess takes as a parameter the path to your game's GDF file. It will check the GDF file's Parental Control rating against the current user's Parental Control settings, and determine whether the current user has the necessary permissions to run this game.

You may wish to inform the user if they do not have 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 the Game Explorer, you must call AddGame with the path to your GDF resource, base install path, and install scope, and optionally an InstanceID 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, Parental Control restrictions may prevent the game install directory from being accessed by the current user.

Step 5. Persist Game InstanceID

Persist 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 a user can perform with your game in the 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 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 the Game Explorer. See Game Explorer Tasks.

Adding the Game to Windows XP

You can install your game to a Windows XP system and store extra information so that your game will show up in the Game Explorer if the user upgrades their 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 Windows XP to Windows Vista.

Step 4. Install Registry Keys

In order to identify your game information so that Windows Vista will add your game automatically upon installation, you must create a set of registry keys. See Windows XP to Windows Vista.