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.

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"
      xmlns:baseTypes="urn:schemas-microsoft-com:GamesExplorerBaseTypes.v1">
    

GameDefinition

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}"
        WMID="{5C08D2FF-A48E-43ca-846C-08924563E5A7}">
    

GameDefinition Attributes

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.

          <ReleaseDate>2004-06-30</ReleaseDate>
     

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.

            <Version>
            <VersionNumber versionNumber="1.2.3.4"/>
            </Version>
      

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.

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

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.

          <Developers>
          <Developer URI="https://www.microsoft.com">Microsoft</Developer>
          </Developers>
     

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.

          <Publishers>
          <Publisher URI="https://www.microsoft.com">Microsoft</Publisher>
          </Publishers>
     

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

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.

          <Genres>
          <Genre>Action</Genre>
          <Genre>Adventure</Genre>
          </Genres>
     

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}"
          path="Game2005"/>
     

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.

          <Ratings>
          <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}" />
          </Rating>
          </Ratings>
     

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.

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.

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.

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.

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

Extended Properties

<RSS>https://go.microsoft.com/?linkid=4058788</RSS>

<GameTasks>
    <Play>
        <Primary>
            <FileTask path="ExampleGame.exe" arguments="" />
        </Primary>
    </Play>
    <Support>
        <Task index="0" name="Support Task Sample">
            <URLTask Link="https://www.microsoft.com" />
        </Task>
    </Support>
</GameTasks>