Games Explorer Tasks

Starting with Windows Vista, users can interact with every game in Windows Games Explorer by using tasks. One example of a task is the action of double-clicking a game in Windows Games Explorer to launch it.

To add tasks for your title

1. Create the task in the Game Definition File Editor tool..

2. Register the task using the GameUXInstallHelper sample.

   You can also use the information in this topic to manually register a task.

This document shows you how and where to register tasks.

Tasks Introduction and Requirements

Tasks are actions that can be taken with an entry in Windows Games Explorer. Tasks determine how a user can interact with a game in Games Explorer. Using tasks, you can determine what happens when the user double-clicks a game in Games Explorer, and what entries show up in the context menu when a user right-clicks a game.

One task, the primary play task, is required for every game. The primary play task is the task that executes when a user double-clicks a game in Games Explorer.

How to Create Tasks

Tasks are associated with a game during installation of the game. For example, they create subdirectories and add shortcuts to these subdirectories associated with the game in Games Explorer. The subdirectories are identified using the InstanceID (a GUID), which was either created and passed into AddGame or was generated and returned by AddGame.

Tasks are defined in the Game-Definition-File (GDF) v2 schema, which is supported by the Windows 7 Game Explorer.

Note that for a Game Provider (defined via a GDF v2 schema), there is a "More Games" link on the interface that will link to the '0'th Support Task defined for the entry.

To associate tasks with a game

1. Install all game files.

2. Call AddGame to add the game to Games Explorer, either by using a custom InstanceID that you designate or by letting AddGame create one for you.

3. Write the GameInstanceID to either a file or the registry for use in uninstalling the game.

4. Create a subdirectory with a name that matches the GameInstanceID, enclosed in braces, in one of the following locations:

   • The common task directory, if the game is installed for all users
   • The per-user task directory, if the game is installed just for the current user

5. Create the task subdirectories in the {GameInstanceID} subdirectory created in the previous step.

   There are two possible subdirectories: PlayTasks and SupportTasks.

6. Add the task shortcuts to the subdirectories created in the previous step.

Task Directory Structure and Rules

When installing your game, you must create subdirectories in specific places for Games Explorer to recognize the tasks inside them. These subdirectories identify whether the task is for all users or for a specific user, the instance of the game being installed, and which types of tasks you are creating (play tasks or support tasks).

To create the proper task directory structure

1. Determine if the game instance is being installed for the current user or for all users, and then do the following:

   • If for the current user, call SHGetKnownFolderPath with FOLDERID_GameTasks to get the current user's Games Explorer data directory.

     Applications that require Windows XP compatibility should use SHGetFolderPath instead. For more information, see Table 1.

   • If for all users, call SHGetKnownFolderPath with FOLDERID_CommonGameTasks to get the common Games Explorer data directory.

     Applications that require Windows XP compatibility should use SHGetFolderPath instead. For more information, see Table 1.

2. Append "Microsoft\Windows\GameExplorer\" to the directory path retrieved in the previous step.

3. Retrieve the InstanceID from the earlier call to AddGame.

4. Create a subdirectory in the previous step's directory, named with the InstanceID in registry format, enclosed in braces.

   For example, {00d8862b-6454-4957-a821-3d98d74c76be}. To make this easier, you can call the StringFromGUID2 function, which formats the GUID properly, including adding the brace characters.

5. Create a subdirectory named PlayTasks under the InstanceID directory from the previous step.

   Also, you can create a subdirectory named SupportTasks if you are presenting support tasks to the user.

6. In the PlayTasks directory, create a directory named 0 (zero).

7. Place the primary shortcut to the game in this subdirectory.

   This shortcut starts the default task when the user double-clicks the game in Games Explorer.

8. For every other task that you want to create, create a subdirectory in one of the three directories from the previous step (PlayTasks or SupportTasks) that is sequentially numbered within that subdirectory.

9. In this numbered subdirectory, place your task shortcut.

   The name of this shortcut is shown to the user when he or she right-clicks the game in Games Explorer. The default task is always called Play.

Table 1. Parent Directories of Games Explorer Task Folders for Different Windows Releases

Example Task Directory Structure for a Game for Different Windows Releases

//for all users
//use ShGetFolderPath with CSIDL_COMMON_APPDATA\Microsoft\Windows\GameExplorer\ as the parent directory

CSIDL_COMMON_APPDATA\Microsoft\Windows\GameExplorer\{00d8862b-6454-4957-a821-3d98d74c76be}\PlayTasks\0\Play.lnk
CSIDL_COMMON_APPDATA\Microsoft\Windows\GameExplorer\{00d8862b-6454-4957-a821-3d98d74c76be}\PlayTasks\1\Play Online.lnk
CSIDL_COMMON_APPDATA\Microsoft\Windows\GameExplorer\{00d8862b-6454-4957-a821-3d98d74c76be}\SupportTasks\0\My Game's Website.lnk

//for the current user only
//use ShGetFolderPath with CSIDL_LOCAL_APPDATA\Microsoft\Windows\GameExplorer\ as the parent directory
CSIDL_LOCAL_APPDATA\Microsoft\Windows\GameExplorer\{00d8862b-6454-4957-a821-3d98d74c76be}\PlayTasks\2\Play Saved Game.lnk    

Example Task Directory Structure for a games only on Windows Vista or later

//for all users
//use SHGetKnownFolderPath with FOLDERID_CommonGameTasks as the parent directory

FOLDERID_CommonGameTasks\{00d8862b-6454-4957-a821-3d98d74c76be}\PlayTasks\0\Play.lnk
FOLDERID_CommonGameTasks\{00d8862b-6454-4957-a821-3d98d74c76be}\PlayTasks\1\Play Online.lnk
FOLDERID_CommonGameTasks\{00d8862b-6454-4957-a821-3d98d74c76be}\SupportTasks\0\My Game's Website.lnk    

Task Rules

Tasks must have the following characteristics:

• A play task consists of one IShellLink or IUniformResourceLocator shortcut. A support task must be a IUniformResourceLocator shortcut.
• A task is associated with an instance of a game installation. An instance is a copy of the game installed for a particular user or all users.
• A task belongs to one of two categories of tasks: play or support. When the user right-clicks on a game in Games Explorer, play tasks and support tasks, are divided from one another by a separator.
• A task shortcut must be placed in a sequentially-numbered subdirectory in the appropriate subdirectory for the task category (PlayTasks or SupportTasks). Each task in a given category must have its own numbered subdirectory. The tasks are displayed in ascending order by numbered subdirectory.
• The task located in PlayTasks\0\ is the primary play task. This task is required. This task is run when the user double-clicks on the game in Games Explorer. The name displayed for this task is Play, regardless of the name of the shortcut.
• Tasks located in the current user's directory override the same task in the common (all users) directory.

Removing Tasks

When you remove your game from the system, use the persistent game InstanceID to find and delete the task directories for the instance of your game that is being removed.