Games Explorer Tasks

Starting with Windows Vista, users can interact with every game in Windows Games Explorer by using tasks. The action of double-clicking a game in Windows Games Explorer to launch it, is an example of task. You can add tasks for your title by:

Create the task in the Game Definition File Editor
Then register the task using the GameUXInstallHelper sample. You can alternatively manually register a task using the information provided in this topic.

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 Windows Games Explorer. Tasks determine how a user can interact with a game in Games Explorer. Using tasks, you can determine what will happen when the user double-clicks a game in Games 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 Games Explorer.

How To Create Tasks

Tasks are associated with a game during installation of the game by creating subdirectories and adding 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.

To associate tasks with a game

Install all game files.
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.
Persist the GameInstanceID for use in uninstalling to either a file or the registry.
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 for the current user only
Create the task subdirectories in the {GameInstanceID} subdirectory created in the previous step. There are two possible subdirectories: PlayTasks and SupportTasks.
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

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 retrieve the current user's Games Explorer data directory. (Applications that require Windows XP compatibility should use SHGetFolderPath instead; see Table 1.)
- If for all users, call SHGetKnownFolderPath with FOLDERID_CommonGameTasks to retrieve the common Games Explorer data directory. (Applications that require Windows XP compatibility should use SHGetFolderPath instead; see Table 1.)
Append "Microsoft\Windows\GameExplorer\" to the directory path retrieved in the previous step.
Retrieve the InstanceID from the earlier call to AddGame. 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.
Create a subdirectory named PlayTasks under the InstanceID directory from the previous step.Optionally, create a subdirectory named SupportTasks if you will be presenting support tasks to the user.
In the PlayTasks directory, create a directory named 0 (zero). Place the primary shortcut to the game in this subdirectory. This shorcut starts the default task for when the game is double-clicked in Games Explorer.
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. In this numbered subdirectory, place your task shortcut; the name of this shortcut will be the name displayed to users when they right-click 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

Name	Legacy CSIDL Definition for use with SHGetFolderPath (Windows XP and Later)	FolderID Definition for use withSHGetKnownFolderPath (Windows Vista and Later)
Tasks for all users	CSIDL_COMMON_APPDATA\Microsoft\Windows\GameExplorer	FOLDERID_CommonGameTasks
Tasks for the current user only user	CSIDL_LOCAL_APPDATA\Microsoft\Windows\GameExplorer	FOLDERID_GameTasks

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