Game Explorer Tasks 

Game Explorer Tasks

Note    This documentation is preliminary and is subject to change.

Every game in the Windows Vista Game Explorer can be interacted with by the user; this is done by way of tasks. An example of a task is launching the game when the user double-clicks on a game in the Game Explorer. This document details how and where to register tasks.

Tasks Introduction and Requirements

Tasks are the name for actions that can be taken with an entry in the Windows Vista Game Explorer. Tasks determine how a user can interact with a game in the Game Explorer. Using tasks, you can determine what will happen when the user double-clicks a game in the Game Explorer, and what entries show up in the context menu when a user right-clicks on 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 on a game in the Game Explorer.

How To Create Tasks

Tasks are associated with a game during the game's installation by creating subdirectories and adding shortcuts to these subdirectories associated with the game in the Game Explorer. The subdirectories are identified using the InstanceID, which was either created and passed into AddGame, or was generated and returned by AddGame.

To associate tasks with a game

1. Install all game files.

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

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

4. Create the "{GameInstanceID}" subdirectory of

   1. The common task directory if the game is installed for all users.
   2. The per-user task directory if the game is installed for the current user only.

5. Create the task subdirectories underneath 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 Game Explorer to recognize the tasks inside them. These subdirectories identify whether the task if for all users or a specific user, the instance of the game being installed, and which types of tasks you are creating (PlayTasks and/or SupportTasks).

To Create The Proper Task Directory Structure

1. Determine if the game instance is being installed for the current user or for all users.
   • IF for the current user, call ShGetFolderPathEx with FOLDERID_GameTasks to retrieve the current user's Game Explorer data directory. (Applications that require Windows XP compatibility should use ShGetFolderPath instead, see the table below.)
   • IF for all users, call ShGetFolderPathEx with FOLDERID_CommonGameTasks to retrieve the common Game Explorer data directory. (Applications that require Windows XP compatibility should use ShGetFolderPath instead, see the table below.)
2. Append "Microsoft\Windows\GameExplorer\" to the directory path retrieved in the previous step.
3. Retrieve the InstanceID from the earlier call to AddGame. Create a subdirectory underneath the previous step's directory, named with the InstanceID in registry format, enclosed in braces, i.e. {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.
4. Create a PlayTasks subdirectory under the InstanceID directory from the previous step.
   • Optionally, create a SupportTasks subdirectory if you will be presenting support tasks to the user.
5. In the PlayTasks directory, create a directory named "0" (zero). Place the primary shortcut to the game in this subdirectory. This task is the default for when the game is double-clicked in the Game Explorer.
6. For every other task you wish to create, create a subdirectory in one of the three directories from the previous step (PlayTasks and/or SupportTasks) that is sequentially numbered within that subdirectory. In this numbered subdirectory, place your task shortcut. The name of the shortcut will be the name displayed to the user when they right-click the game in the Game Explorer. The default task is always called Play.

Parent Directories of Game Explorer Task Folders for Windows XP and Windows Vista

Example Task Directory Structure for a Windows XP and Windows Vista Game

//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 Windows Vista Only Game

//for all users
//use ShGetFolderPathEx 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
 
//for the current user only
//use ShGetFolderPathEx with FOLDERID_GameTasks as the parent directory
FOLDERID_GameTasks\{00d8862b-6454-4957-a821-3d98d74c76be}\PlayTasks\2\Play Saved Game.lnk

Task Rules

• A task consists of one IShellLink or 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: PlayTasks or SupportTasks. When the user right-clicks on a game in the game explorer, PlayTasks and SupportTasks, will be divided from one another by a separator.
• A task shortcut must be placed in a sequentially-numbered subdirectory underneath the appropriate task category subdirectory (PlayTasks, SupportTasks). Each task in a given category must have its own numbered subdirectory. The tasks will be displayed in ascending order by numbered subdirectory.
• The task located at PlayTasks\0\ will be the primary play task. This task is required. This task will be run when the user double-clicks on the game in the Game Explorer. The name displayed for this task will be Play, regardless of the name of the shortcut.
• Tasks located in the current user's directory will override the same task in the common (all users) directory.

Removing/Uninstalling Tasks

When uninstalling your game, use the persisted game InstanceID to find and delete the task directories for the instance of your game that is being uninstalled.