The Game-Definition-File (GDF) Schema

The first step in preparing your game title to be displayed in Windows Vista Game 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

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 that the path is relative to. 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(s).

<Developers>
  <Developer URI="http://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(s).

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

WindowsExperienceIndex (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 that a particular computer has. The WindowsExperienceIndex element specifies the recommended and minimum WEI ratings that a computer should have for acceptable performance. This is for display purposes only and does not restrict access to the game.

<WindowsExperienceIndex minimum="4" recommended="5"/>

WindowsExperienceIndex Attributes

Genres (multiple elements with boundedString type, optional)

Genres is a set of 1-5 publisher elements that specify the names and respective URLs of the game publisher(s).

<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. Each rating can optionally have one or more content descriptors that are associated with that rating. Ratings, rating systems, and descriptors are GUIDs that are defined in ratings.dll.

<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 rating assignment is used by the parental controls feature of game explorer 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. The ratings system to use can also be changed within the parental controls settings.

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 and 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 includes 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 General Application Restrictions is enabled, 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 General Applications Restrictions is enabled.

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%) then the path is treated as an absolute path and Game 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 wish 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.

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