Game Definition File Editor: Tool Tutorial

This section describes how to use the Game Definition File (GDF) Editor to create localized game definition files. For a reference guide to the GDF Editor, see Game Definition File Editor (gdfmaker.exe).

Figure 1.  Main window of Game Definition File Editor

Tutorial: Using the Game Definition File Editor

This tutorial leads you through the creation of a sample GDF project, consisting of the following steps:

• Step 1: Start the Game Definition File Editor
• Step 2: Create a New Project
• Step 3: Change the Game ID GUID
• Step 4: Edit Game Title and Metadata
• Step 5: Select Game Windows Experience Index
• Step 6: Select Game Ratings
• Step 7: Select Allowed Executables
• Step 8: Specify Genres, Developers, and Publishers
• Step 9: Specify Play and Support Tasks
• Step 10: Specify the Provider and RSS feed
• Step 11: Add Thumbnail and Icon
• Step 12: Edit Language-Specific Data
• Step 13: Build the Project into a resource file
• Step 14: Build a GDF binary from the resource file

Step 1: Start the Game Definition File Editor

On the Start menu, navigate to the DirectX SDK, point to DirectX Utilities, and then click Game Definition File Editor.

Alternatively, you can start the command line; the name of the executable file is GDFMaker.exe, and it is located in DirectX SDK root \Utilities\Bin\ platform \.

The Game Definition File Editor starts with no data loaded.

Step 2: Create a New Project

In this step, you create a new GDF project by selecting a file name, a location for the project file and its language-specific subdirectories, and the languages that your title will be localized to.

To create a new project

1. Click the New project icon on the toolbar.

   

2. In the New Game Definition Project window, select the language-locale combinations that your title supports. You can add additional selections to your project later.

   

3. Enter the name of your game definition project in the Project Name edit control.

   Then enter the project source path in the Project Location edit control. Alternatively, you can click Browse to select an existing folder.

   When you are finished, click OK to continue.

The Game Definition File Editor window now displays a list of the selected languages and generates default values.

After you save the new project, the editor creates a project file and a new directory for each of the languages that you selected in New Game Definition Project. These new directories are created under the project directory.

Each of these entries is represented by a corresponding property page in the right-side pane of the Game Definition File Editor window. Every locale that is listed under Localization Information has its own settings. To see the settings for a particular locale, select the locale from the list, and the properties shown on the right will be refreshed to show the settings associated with the selected locale. When the fields in a property page are filled, the editor can build the corresponding portions of the GDF, and the resources (.rc) file can reference it.

The language-neutral entry contains settings that will be used across all languages, and some of these settings will be used as defaults when a language-specific page lacks a setting. This tutorial starts by adding data to this entry's property page, and then it covers the language-specific properties.

Step 3: Change the Game ID GUID

The Game ID control contains a unique GUID that is used to identify your game in Games Explorer. A GUID is automatically generated for you when you create a new GDF project. This GUID is also used to register, remove, update, or verify a game title when calling methods of the IGameExplorer interface. It should be noted that the game identifier of the game applies to all locales. There is normally no need to change this, but you can change or generate a new GUID by clicking the ellipses button (...) button to the right of the text box.

To generate a new game ID

1. Click the ellipses button (...) button to the right of the text box to open Game Identifier Editor.

   

2. Click Generate ID to generate a new GUID for your game ID.

3. Then click OK to apply the change.

Step 4: Edit Game Title and Metadata

The first set of data to edit is related to general game information: title, description, and other metadata. The following figure shows a portion of a property page.

Enter data into each of the fields of the property page, using the field names and descriptions in the follow table as a guide.

Field	Description
Game Name	The name of your game. This is displayed as the name of the game in Games Explorer.
Description	The description of your game. This text is not currently used in Games Explorer, but it may be used in the future.
Release Date	The release date of your game. The date is displayed in the metadata section of Games Explorer when the user selects your game.
Saved Games Folder	A relative path to where your game will store saved games files. The drop-down box to the left of the text field allows you to set the location to which this path is relative. You should choose a path that specifies a location that a Standard User will have read and write access to. For more details, see the Gaming with Least-Privileged User Accounts technical article. Note Unless this value is set to Not Specified, you may extend the path indicated by the selected item by entering an addition path string in the Subdirectory edit control. Saved Games Folder can be set to one of the following: Not Specified Default Game Folder User's Application Data My Documents User's Local Application Data Program Files Saved Games
Subdirectory	Allows you to extend the directory path that is specified by Saved Games Folder. For example, if the selected item is Program Files, and you enter ExampleGameUserSaves in Subdirectory, then the folder path for saved games will be %SystemDrive%\Program Files\ExampleGameUserSaves\.
Version	Either a version number in four-part format ( a.b.c.d ), or a relative path from the game's installation directory to a DLL or executable file that will be queried for a version number. Use the drop-down box to choose either Version or File.

Step 5: Select Game Windows Experience Index

The Windows Experience Index (WEI) is a measure of the overall performance of a computer system running Windows Vista. Games Explorer will display the WEI values when users select listed games that indicated WEI support. This setting is optional, and is used to inform the user if their system performance can optimally handle the game title. As of this writing, the WEI ratings range from 1.0 to 6.0, with 6.0 being equal to the highest performing desktop computer currently available. The test team working on the game title, or marketing, should be able to provide an accurate minimum and recommended WEI values.

Step 6: Select Game Ratings

Your game can also have content ratings associated with it. These content ratings can come from the rating system of one or more organizations, like the Entertainment Software Ratings Board (ESRB) and Pan-European Game Information (PEGI).

The content rating assignment is used by the parental controls feature of Games Explorer to limit which installed games can be viewed and run. By default, the parental controls reference the content rating identifier for the rating organization that best fits the locale setting in Regional and Language Options in Control Panel. The ratings organization to use can also be changed within the parental controls settings.

To add a game rating

1. Click Add in the Game Rating Information area.

   This opens Add Rating Dialog.

   

   For this tutorial, select Entertainment Software Ratings Board (ESRB).

   Note

   A hyperlink to detailed information about a rating service is located immediately below the service's icon.

   

2. If the ratings system uses ratings symbols, select one by clicking the currently displayed symbol. Since the rating system of the ESRB does use symbols, we are able to select a symbol in this tutorial.

   

   Choose a rating symbol from the list that is displayed when you click the currently displayed symbol. A definition of a rating symbol is displayed when the pointer hovers over the symbol.

   

3. If the ratings system uses content specifiers, select those that apply to your game.

   Note

   Several ESRB content specifiers have been added since Windows Vista SP1, and these are fully supported by Game Definition File Editor. Games that use these new content specifiers, when installed on versions of Vista prior to SP1, will be reported by Game Explorer as unrated (to avoid showing a partial rating).

4. Repeat this procedure to add as many rating systems and ratings as you want. You might need to use the scroll bar to see all of the ratings that you have added.

Step 7: Select Allowed Executables

General Application Restrictions is a feature that, if enabled, prevents all executable files from running except for those that are explicitly allowed. When General Application Restrictions is enabled, the executable files listed in a GDF from a signed source are automatically allowed, based on the parental controls settings.

In general, the path to an allowed executable file is relative to a game's installation root directory. This root directory is specified by the bstrGameInstallDirectory argument of the IGameExplorer::AddGame method which registers a game with Games Explorer.

An exception to this occurs when a path begins with an environment variable that is bounded by percent signs, such as %TEMP%; in such a case, the path is treated as an absolute path, beginning from the path indicated by the environment variable.

For more information about specifying the executable files that are required for a game to run, see the GDF Schema: GameExecutables technical article.

Continuing with the tutorial, for every executable file that your game will run, add an entry to the list of allowed executable files.

To add an executable file as allowed

1. Click Add on the Executables tab.

2. Edit the newly created entry to specify a path and executable file, and then press ENTER.

   Note

   Executable paths must always be relative to the game's installation directory.

Step 8: Specify Genres, Developers, and Publishers

You select genres to classify your game, as well as add names and URIs for the developers and publishers, at the bottom of the property page.

To specify genres for your game

1. Click the Genres tab.

2. Click Add.

3. From the list in Genre Editor, select all of the genres that you want to specify.

   

4. Click OK to save your selections.

To specify developers or publishers for your game

1. Click the Developers tab or the Publishers tab.

2. Click Add.

3. In the dialog box that appears, enter the name of the developer or publisher in the top field. In the bottom field, enter a full URI to the Web site for the developer or publisher (for example, https://www.gamesforwindows.com).

   

4. Click OK to specify the developer information.

Step 9: Specify Play and Support Tasks

Game Definition File Editor allows developers to associate shortcut paths and URL links to files with executables in your game definition. There are two types of tasks that you can add to your game's GDF: play tasks and support tasks.

Play Tasks

Play tasks allow you to specify a variety of actions for any executable file that is applicable to the game. The primary task should always be the game's main executable file. Secondary file tasks allow you to launch additional game executable files, or launch the main executable file with different parameters. For example, you can create a secondary play task that launches your game in safe mode ("game.exe -safemode") and another play task that launches the game in multiplayer mode ("game.exe -multi").

A play task can also allow you to associate a URL that users can navigate to from Games Explorer. For example, a play task could link the user to a Web site, maintained by the game's developer, that offers game-related news. Play task could also provide links to the game's multiplayer leaderboards, a web page that lists other titles available from the developer, and user-generated content.

Support Tasks

Support tasks allow you to specify support-related files and URLs that are applicable to the game. You can associate any diagnostic utilities that troubleshoot problems with your game as support file tasks.

A support task also allows you to provide a URL that users can navigate to for online help and support. For example, a support task could link to a Web site, maintained by the game's publisher, that provides status information about game servers.

To add a play task to your game's GDF

1. Click the Play Tasks tab.

   

2. Click Add to open the Play Task dialog box.

   

3. In Play Task, enter the following settings:

   • Type
     Specifies whether the play task is a Primary Task or a Secondary Task.

   • Sub Type
     Specifies whether the support task is a File Task or a URL Task.

   • Index
     Specifies the order of the play task. The valid integer range is between 0 and 100. If the index value is 0, the task is considered the primary play task.

   • Name
     Name of the play task. Specifying a name is optional.

   • Folder
     Specifies the location of the base folder for the play task executable files. This field is only valid when the Sub Type is set to File Task.

   • Path
     The path and file name of the executable file relative to the directory specified in Folder. This field is only valid when Sub Type is set to File Task.

   • Arguments
     Specifies any arguments that will be passed to the play file executable. This field is optional. This field is only valid when Sub Type is set to File Task.

   • URL
     Specifies the URL associated with the play task. This field is only valid when Sub Type is set to URL Task.

4. To create the play task, Press OK.

To add a support task to your game's GDF

1. Click the Support Tasks tab.

   

2. Click Add which to open the Support Task dialog box.

   

3. Fill in the settings in Support Task. It contains the following user settings:

   • Sub Type
     Specifies whether the type of support task, File Task or URL Task.

   • Index
     Specifies the order of the support task. The valid integer range is between 0 and 100. If the index value is 0, the task is considered the primary support task.

   • Name
     Name of the support task. Specifying a name is optional.

   • Folder
     Specifies the supported folder locations where the support file task resides. This field is only valid when Sub Type is set to File Task.

   • Path
     Path and file name of the executable file, relative to the directory specified by Folder. This field is only valid when Sub Type is set to File Task.

   • Arguments
     Specifies any arguments that will be passed to the support file executable. This field is optional, and it is only valid when Sub Type is set to File Task.

   • URL
     Specifies the URL to the support URL task. This field is only valid when Sub Type is set to URL Task.

4. To create the support task, Press OK.

Step 10: Specify the Provider and RSS feed

If there is an RSS feed associated with the game, you will want to make sure to provide its URL in the XML file.

To specify that this GDF defines a provider rather than a game

1. Click the Provider tab.

   

2. Select This item is a Game Provider.

3. Enter the URL of the provider's RSS feed.

   

Step 11: Add Thumbnail and Icon

Your game is represented in Games Explorer by a thumbnail image, and in some cases, an icon file. You should provide box art or a similar type of logo for your thumbnail image.

When your game is viewed in Games Explorer:

• The thumbnail is used when Games Explorer is viewed in Extra Large Icons and Large Icons modes.
• The icon is used when Games Explorer is viewed in Details mode.

For information about acceptable formats and sizing recommendations for your thumbnail image, see the Thumbnail Formats section of the GDF Delivery and Localization overview.

To choose a thumbnail image and icon for your game

1. Click Add Thumbnail or Add Icon.

2. In the dialog box that appears, browse to an image file to use for your thumbnail image or icon. For thumbnail images, the drop-down list of file types in the dialog box is the list of all of the file types that you can use for your thumbnail. For icons, only Windows icon files can be used.

3. Click OK. The thumbnail image or icon will be automatically copied to the appropriate directory in your GDF project and displayed in the Game Definition File Editor window, as shown in the following figure.

   

   Note

   The following resolutions for icon files are recommended:

   • 16×16 (256-color)
   • 16×16 (RGB/A)
   • 32×32 (256-color)
   • 32×32 (RGB/A)
   • 48×48 (256-color)
   • 48×48 (RGB/A)
   • 256×256 (256-color)
   • 256×256 (RGB/A)

Step 12: Edit Language-Specific Data

At this point, all of fields in the language-neutral property page should be populated. Next, each language-specific property page must be populated with data that is specific to the language, such as a localized title, description, version, thumbnails, and so on.

Data is not automatically copied to language-specific pages from the language-neutral page — except for the Game ID, Windows Experience Index, and Game Ratings. All other data must be entered for each language-specific page.

To enter data for language-specific property pages

1. Select a language under Localization Information in the Game Definition File Editor window.

   

2. Enter data in the properties shown in the pane to the right of Localization Information, as described in the preceding steps in this tutorial.

3. Repeat until you have entered data for each set of language-specific properties.

Step 13: Build the Project into a resource file

With the fields on all of the property pages filled, you can build your project into a resource file and header file that can be used to compile the GDF data into a DLL or executable file.

The final results of building a project are following:

• For each language and for language-neutral, the editor creates a directory under the GDF project directory named with a language abbreviation (such as ENU for English and FRA for French). Each of these directories contains the GDF and the thumbnail and icon graphics for that language.
• The editor creates a .rc file and a .h file in the main GDF project directory that references the GDF resources in each of the language subdirectories.

To build your project

1. On the Resources menu, click Build Script for Project.
2. A message box will appear to inform you whether the resource file was created successfully, or if it failed. The newly created file is then copied into the localization folder that is associated with the selected language.
3. Click OK to return to the Game Definition File Editor.

Step 14: Build a GDF binary from the resource file

Next you must compile the GDF data into a DLL or executable file by using the .rc file, created when you built the GDF project. This DLL or executable file should be installed by the game's installer, and its path should be passed to the Games Explorer APIs during the installation process. GDFExampleBinary, a sample provided with the DirectX SDK, has the GDF data compiled into a DLL.