Getting Started with Games Explorer
Windows Games Explorer provides game developers with a secure and attractive way to present their games to users of the Windows platform (starting with Vista). This document details how to add a game to Games Explorer.
What is Games Explorer?
Windows Games Explorer is a custom folder for the Windows shell that provides a rich presence for games. It is accessed on the Start by clicking Games.
Games 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
Display of game statistics
Display of game notifications
Display of game providers with optional news feeds
Using Games Explorer
To enable your game to use Games Explorer, you must create the data files that Games Explorer relies on, and add your game to Games Explorer.
- Creating Games Explorer Data Files
- Adding a Game to Games Explorer
- Enabling Games Explorer on a Domain
Creating Games Explorer Data Files
The first part to adding a game to Games Explorer is to create and properly include a set of data that is consumed by Games Explorer. Doing this consists of the following steps.
Step 1. Create GDFs
Games 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 Games 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
Games 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 Games Explorer.
The image should be in PNG format, as this allows for transparency features to give your artwork a clean look in the Games 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 Games 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 Games Explorer header (GameUx.h) contains defined constants that you must use in the resource script to identify your GDF and bitmap file so that Games Explorer can find them. By separating the resource script into sections with #ifdef for multiple languages, you can instruct Games Explorer to search for localized versions of GDF files and bitmaps.
For more information, see GDF Delivery and Localization.
Adding a Game to Games Explorer
The second step to adding a game to Games Explorer is performed by the game's installer. The installer's code must identify the location of the game data for Games Explorer. Because Games Explorer is only available on Windows starting with Vista, a different set of steps must be taken for an installation on a computer running Windows XP as opposed to on one running a more recent version of Windows. Games that do not use an installer can perform these tasks at launch time, if necessary.
- Adding a Game to Recent Versions of Windows
- Adding a Game to Windows Vista, Windows 7, or Windows 8 Desktop
- Adding the Game to Windows XP
Adding a Game to Recent Versions of Windows
If a game is installed on a recent version of Windows (Windows 7 or later), see the Windows Games Explorer for Game Developers technical article for instructions on how to add your game.
Adding a Game to Windows Vista, Windows 7, or Windows 8 Desktop
If a game is installed on Windows Vista, Windows 7, or Windows 8 Desktop, 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 Games 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 Games 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 Games 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 Games 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 Games 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 Games 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 Games Explorer. See Games 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 Games Explorer if the user upgrades the system to a more recent version of Windows.
Step 1. Install Game Files
As in the scenario for more recent versions of Windows, 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 Games 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 scenario for installation with more recent versions of Windows, 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 Games Explorer when the user upgrades to a newer version of Windows, such as Windows Vista or Windows 7. See Games Explorer Tasks as well as Supporting an Upgrade from Windows XP.
Step 4. Install Registry Values
So that a more recent version of Windows 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 Games Explorer on a Domain
To use parental controls on a Windows system joined to a domain, you must change a group policy setting to make parental controls visible:
Navigate to Local Computer Policy | Computer Configuration | Administrative Templates | Windows Components | Parental Controls.
Set "Parental Controls control panel visible on a Domain" to enabled.
Log off and parental controls will be visible.
- 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.
- Games Explorer Tasks
- The topics provided here provide a detailed explanation of the Games 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.