The Game-Definition-File (GDF) Schema

The first step in preparing your game title to be shown in Windows Games Explorer is to create a game definition file (GDF). A GDF is XML that must adhere to the GDF schema, which is described in this topic.

Base Types

The GDF schema refers to a set of base data types that are defined in a separate schema. These types are shown in the following table.

NameSchema ComponentTypeDescription
fourPartVersionsimpleTypestring (with facets)A simple type that contains a regular expression for 4-part versions (0-65535.0-65535.0-65535.0-65535).
GUIDsimpleTypestring (with facets)A simple type that contains a regular expression for GUIDs. GUIDs must be of the standard type, enclosed in braces, and following the pattern {AAAABBBB-CCCC-DDDD-EEEE-FFFFGGGGHHHH}.
boundedStringsimpleTypestring (with facets)A string that preserves white space, and is limited to 32,768 characters.
filePathAttributeGroupattributeGroupn/aTwo frequently-used attributes for file paths, combined.
filePathAttributeGroup: baseKnownFolderIDattributeGUIDA GUID that represents a KnownFolder as the base path for folders. The path is relative to this known folder. If this folder isn't specified, the path attribute, filePathAttributeGroup, is relative to the game's installation directory.
filePathAttributeGroup: pathattributeboundedStringA bounded string for the file path represented by this group. This file path is relative to baseKnownFolderID.

Root Element: GameDefinitionFile

GameDefinitionFile is the root element of the GDF's XML, and it contains all of the imported namespaces.

      <GameDefinitionFile xmlns="urn:schemas-microsoft-com:GameDescription.v1"


GameDefinition is the actual root element of a game definition, and it contains two attributes, gameID and WMID.

        <GameDefinition gameID="{5C08D2FF-A48E-43ca-846C-08924563E5A7}"

GameDefinition Attributes

gameIDGUIDThe game ID. This uniquely identifies your game title to Games Explorer. This is generated by you, or in the case of certain titles, has already been provided. See Legacy Game Support with Games Explorer.
WMIDGUIDThe game ID for Windows Metadata Services. This should only be used for legacy games.

ExtendedProperties (optional)

This data type is only consumed by Windows 7 or later verisons of Game Explorer, and provides extneded information. See "Extended Properties" below.

Name (boundedString)

Name boundedString type that provides the name of the game.

          <Name>Super Game 2005</Name>

Description (boundedString, optional)

Description is a boundedString type that provides a description of the game.

          <Description>The Penultimate Game</Description>

ReleaseDate (date, optional)

ReleaseDate is the date of the game's release, in standard XML date format, YYYY-MM-DD.


Version (version)

The Version element is a choice type which contains one of the two ways of specifying the version number of your game. One method is an explicit version number embedded in the XML, VersionNumber. The other method is a path to an executable or DLL, where the version number can be extracted, VersionFile.

VersionNumber (fourPartVersion)

VersionNumber is a version number.

            <VersionNumber versionNumber=""/>
VersionFile (element with filePathAttributeGroup)

VersionFile provides the path to an executable or DLL file that contains version information. This element can contain a baseKnownFolderID attribute (a GUID) to indicate a location to which the path is relative. Not having a baseKnownFolderID attribute will make the path relative to the game's installation directory.

            <VersionFile path="bin\MyGame.exe"/>

Developers (multiple elements with link type, optional)

Developers is a set of 1-5 developer elements that specify the names and respective URLs of the game developer or developers.

          <Developer URI="">Microsoft</Developer>

Publishers (multiple elements with link type, optional)

Publishers is a set of 1-5 publisher elements that specify the names and respective URLs of the game publisher or publishers.

          <Publisher URI="">Microsoft</Publisher>

WindowsSystemPerformanceRating (untyped element with several attributes, optional)

Windows Experience Index (WEI), a feature of Windows Vista, is an floating-point number that specifies a level of performance by a particular computer. The WindowsSystemPerformanceRating element specifies the recommended and minimum WEI ratings that a computer should have for acceptable performance. This is for display purposes only, and it does not restrict access to the game.

          <WindowsSystemPerformanceRating minimum="4" recommended="5"/>
WindowsSystemPerformanceRating Attributes
minimumfloatThe minimum WEI rating that a computer should have in order to play this game.
recommendedfloatThe recommended WEI rating that a computer should have in order to play this game.

Genres (multiple elements with boundedString type, optional)

Genres is a set of 1-5 genre elements that specify the names and respective URLs of the game publisher or publishers.


SavedGames (element with filePathAttribute, optional)

SavedGames identifies the folder where saved games will be placed. As with the VersionFile element, this element can have an optional baseKnownFolderID element that starts the path with a known folder. If it is omitted, the path attribute will be relative to the game's installation directory.

          <SavedGames baseKnownFolderID="{5C08D2FD-A48E-43ca-846C-08924563E5B7}"

Ratings (elements with sub-elements that contain GUIDs, optional)

Ratings describes the parental controls ratings associated with the game. Multiple ratings are allowed, from multiple rating systems. As an option, each rating can have one or more content descriptors that are associated with that rating. Ratings, rating systems, and descriptors are GUIDs that are defined in Utilities\Source\GDFTrace\ratings.xml.

          <Rating ratingID="{5C08D2FD-A48E-43ca-846C-08924563E5B7}"  ratingSystemID="{5C08D2FE-A48E-43ca-846C-08924563E5A7}">
          <Descriptor descriptorID="{5C08D2FD-A48E-43ca-846C-08924563E5C7}" />
          <Descriptor descriptorID="{5C08D2FD-A48E-43ca-846C-08924563E5B7}" />

The parental controls feature of game explorer uses the rating assignment to limit which installed games can be viewed and run. By default, the parental controls reference the rating ID for the ratings system that is appropriate to Vista's locale setting in the Regional and Language Options of the Control Panel. You can use the parental controls settings to select a ratings system other than the default setting.

Rating (element with a ratingID and ratingSystemID attributes)

The Rating element specifies the rating ID and rating system ID that specifies a game rating, such as "T for Teen" in the ESRB system.

Rating Attributes

The following table shows the attributes for the Rating element.

ratingIDGUIDThe specific rating, such as "T for Teen."
ratingSystemIDGUIDThe rating system that the rating corresponds to, such as the ESRB rating system.

Descriptor (element with a descriptorID attribute)

This is a content descriptor for a specific rating. You can have one or more descriptors for each rating.

Descriptor Attribute

The following table shows the attribute for the Descriptor element.

descriptorIDGUIDA content descriptor for the rating.

GameExecutables {type: multiple elements of type GameExecutable, optional}

GameExecutables defines a list of executable files that are required for an application to run. This list of files is required for a game to be part of the Games for Windows program. It is very important that the application list all of the executable files that it installs or extracts (including copy protection, which is extracted at run time) in this section to ensure proper behavior with parental controls.

Parental controls include a feature called General Application Restrictions, which allows a user to execute only those applications that have been specifically approved by the administrator. This blocking is achieved at the CreateProcess layer, using Software Restriction Policies in Windows Vista.

When you enable General Application Restrictions, the executables listed in the application's signed GDF are automatically exempted or allowed based on the Games Parental Controls settings.

Including a GameExecutables section in the GDF allows the application to run with minimal interference when you enable General Applications Restrictions.

GameExecutable {type: none, with a path attribute of type: boundedString}

GameExecutables has a required path element which is relative to the application's installation directory.

If the path begins with an environment variable (such as %TEMP%), the path is treated as an absolute path and Games Explorer will replace the environment variable at run time. If a path starts with a percent sign and is not a real environment variable (for example, %FAKE%), the text will be taken literally. You should not have any percent signs in your game path whatsoever.

BaseKnownFolderID is not supported in this context because it is not supported by the Software Restrictions Policy system.

Important: Environment variable replacement is really only meant to support situations where your game, at run time, extracts a file into a temporary folder. It is supported only in the GameExecutable element, and is not applicable elsewhere in the game definition file. If you want to use this feature, you cannot have percent signs in your folder paths.

If you do not use environment variables and, instead, specify a path, such as "bin\\mygame.exe", the path will be relative to the subdirectory of your game installation directory as passed to IGameExplorer::AddGame when you register your game.

        <GameExecutable path="bin\game.exe"/>
        <GameExecutable path="bin\gamecopyprotection.exe"/>
        <GameExecutable path="support\gamesettingswizard.exe"/>
        <GameExecutable path="%TEMP%\~e5.0001"/>

Extended Properties

TypeThis indicates if the entry is for a Game Title (<Type>0</Type>), which is the default, or a Game Provider (<Type>1</Type>). Note: For a Game Provider, there is a "More Links" displayed on the interface that uses the URL provided for the 0th support task.
RSSFor a Game Provider, this provides a URL to the RSS feed to show in the interface. This is ignored for a Game Title.
Game TasksWith GDF v1, Game Tasks were defined as directories and shortcuts (see "Games Explorer Tasks"). For GDF v2, they are included as part of the GDF. They are defined within the ExtendedProperties block. One of the "Play" tasks should be defined as the "Primary" which is the default when the entry is double-clicked.
            <FileTask path="ExampleGame.exe" arguments="" />
        <Task index="0" name="Support Task Sample">
            <URLTask Link="" />

Community Additions