Game Definition File Editor 

  • Article

Game Definition File Editor

Note    This documentation is preliminary and is subject to change.

The Game Definition File Editor is a graphical utility designed to help you create valid, localized Game Definition Files (GDF) as well as the necessary Resource Compiler scripts to compile them into a target binary. The Game Definition File Editor uses a project-based format to organize GDF data.

The Game Definition File Editor is available in the latest DirectX SDK.

Tutorial: Using the Game Definition File Editor

This tutorial will lead you through the creation of a sample Game Definition File project. These are the steps:

  • Step 1: Start Game Definition File Editor
  • Step 2: Create a New Project
  • Step 3: Edit Game Title and Metadata
  • Step 4: Select Game Ratings
  • Step 5: Select Allowed Executables
  • Step 6: Add Genres, Developers, and Publishers
  • Step 7: Add Thumbnail and Icon
  • Step 8: Edit Language-Specific Data
  • Step 9: Build the Project into a resource file
  • Step 10: Build a GDF binary from the resource file

Step 1: Start Game Definition File Editor

From your Start Menu, select All Programs, Microsoft DirectX SDK, DirectX Utilities, and then select Game Definition File Editor.

- OR -

Run the exe from this location:

(Installed SDK Location)\Utilities\Bin\x86\GDFMaker.exe

Step 2: Create a New Project

The Game Definition File Editor will start with no data loaded.

Click the "New Project..." icon on the toolbar.

You will be asked to select a location and a name for your project file. Enter a name in the text field and click OK.

A dialog will appear, asking for a name for your project, and a selection of languages to localize to.

You can add languages to your project later if you need to. Once you have entered a project name and chosen your supported languages, click OK.

A project file will be created by the tool, and a directory for each language you selected will be created under the project directory. At the same time, you will see the project appear as a node in the left-hand pane of the Game Definition File Editor window.

Left click on the plus icon to the left of the project node to expand your project. You will see one or more entries below the node:

Each of these entries represents a separate tab of data in the Game Definition File Editor. When a tab is filled out, it can be built into a Game Definition File and referenced by the resource file (.rc) created by this tool.

The first entry is the language-neutral entry. Double clicking on it will bring up its tab. This entry's tab contains data that will be used across all languages, and some of this data that will be used as defaults in case a language-specific page is missing data. We will start by adding data to this entry's tab, and then move to the language-specific tabs.

Step 3: Edit Game Title and Metadata

The first set of data to edit is related to general game information - title, description, and other metadata.

Fill out these fields, using the below table to understand their meanings:

Field Usage
Game ID An auto-generated GUID that identifies your game to the IGameExplorer methods. There is normally no need to change this, but you can change or generate a new GUID by clicking on the "..." button to the right of the field.
Game Name The name of your game. This will be displayed as the name of the game in the Game Explorer.
Description The description of your game. This field is not currently used in the Windows Vista Game Explorer, but may be used in the future.
Release Date The release date of your game. Displayed in the metadata section of the Game 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 where this path is relative to. It is recommended that you choose a path for save games where a Standard User will have read/write access to. For more details see the "Gaming with Least-Privileged User Accounts" article in the DirectX SDK.
Version Either a version number in four-part format (a.b.c.d), or a relative path from the game's install directory to a DLL or executable file that will be queried for version number. Use the drop-down box to choose either Version or File.
Windows System Performance Rating A minimum and recommended WSPR number for this game. A WSPR number is a measure of the overall performance of a computer system. As of Windows Vista Beta 2, the WSPR ratings range from 1 to 5, 5 being equal to the most high-performance desktop computer currently available. Numbers larger than 5 may be possible over time as hardware performance improves. The Game Explorer will display this information when the user selects your game.

Step 4: Select Game Ratings

Your game can also have content ratings associated with it. These content ratings can come from one or more organizations. You select one or more of these organizations, choose your ratings, and add content specifiers.

To add a game rating

  • Click on the drop-down box to the left of the "Add Rating" button to select a rating system to add. Click the Add Rating button.
  • To choose the rating for your game in this rating system, and click on the rating graphic.
  • Then choose a rating from the list that appears.
  • Add any content specifiers by clicking checkboxes next to the specifiers you wish to add.
  • Repeat for as many ratings as you wish to add. Adding multiple ratings will simply extend the content in the rating box; use the scroll bar to see the additional ratings.

Note    For the ratings to be interpreted and displayed by the Game Explorer, you must digitally sign the DLL or executable file that holds the GDF data using a trusted Certificate Authority. If your game is not signed, your game will be simply be interpreted by the Windows Vista Parental Controls system as an unrated game even if you have rating data in your GDF. See Authenticode Signing for Game Developers for more details about code signing.

Step 5: Select Allowed Executables

In Windows Vista, General Application Restrictions is a feature that if turned on prevents all but explicitly allowed executables from running. When General Application Restrictions is enabled, the executables listed in a GDF from a signed source are automatically exempted/allowed based on the Games Parental Controls settings.

For every executable that your game will run, add an entry to the Allowed Executables list.

The path is relative to your game's install directory unless it begins with an environment variable bounded by %, such as %TEMP%, in which case the path is treated as an absolute path, beginning from the path pointed to by the environment variable. See GDF Schema: GameExecutables for more information.

Step 6: Add Genres, Developers, and Publishers

The bottom-most set of tabs allow you to classify your game by genre, as well as add names and URLs for the developers and publishers of your game.

To select genres for your game

  • Click the Genres tab.
  • Click the "Add..." button.
  • From the list that appears, check all genres you wish to add, and click OK.
  • If you have clicked the {New Genre} button, the genre will automatically highlight. Type in a name for this genre and press Enter. While adding a new genre is possible, it is not recommended; if possible try to use existing genres to define your game.

To add developers/publishers for your game

  • Click the Developers or Publishers tab.
  • Click the "Add..." button.
  • In the dialog that appears, enter the name of the developer or publisher in the top field. In the bottom field, enter a full URL to the website for the developer or publisher (ex. "https://www.msn.com"). Click OK.

Step 7: Add Thumbnail and Icon

Your game is represented in the Game 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 viewing your game in the Game Explorer:

  • The thumbnail is used when the Game Explorer is viewed in tiles mode, or in all "icon" modes (extra large icon to small icon).
  • The icon is used when the Game Explorer is viewed in details mode.

For information about acceptable formats and sizing recommendations for your thumbnail image, see Thumbnail Formats.

To choose a thumbnail/icon for your game

  • Click the "Add Thumbnail..." or "Add Icon..." button.
  • From the dialog that appears, browse to a graphics file you wish to use for your thumbnail or icon. For thumbnails, the drop-down list of file types in the dialog is the list of all of the file types you can use for your thumbnail. For icons, only Windows icon files can be used.
  • Click the OK button. The thumbnail or icon will be automatically copied to the appropriate directory in your GDF project.

Step 8: Edit Language-Specific Data

At this point, all fields in the language-neutral page are populated. Each language-specific page must now be populated with data specific to the language, such as a localized title, description, version, thumbnails and so on. Data is not auto-populated into language-specific pages from the language-neutral page, except for the Game ID, WSPR, and Ratings. All other data must be entered for each language-specific page. Double click on each language in turn to open its tab and fill in its data.

Step 9: Build the Project into a resource file

With a fully-filled out set of pages, you can build your project into an resource file and header file that can be used to compile the GDF data into a DLL or executable file.

To build your project

From the toolbar, select Resources - Build Script for Project, or click the Build Resource Script for Project button on the toolbar.

In the dialog that appears, choose a name for your resource file. Place the resource file in the same directory as your GDF project.

Click OK.

The final results of the build will be:

  • For each language (including language-neutral), a directory will be created under the GDF project directory named with a language abbreviation (such as ENU for English or FRA for French) and containing the GDF XML file and thumbnail/icon graphics for that language.
  • A .RC file and .H file in the main GDF project directory that references the GDF resources in each language subdirectory.

Step 10: Build a GDF binary from the resource file

Next you must compile the GDF data into a DLL or executable file using the .RC created above. This DLL or EXE should be installed by the game installer, and its path passed into the Game Explorer APIs during the install process. The GDFExampleBinary sample provided in the DirectX SDK that is an example of compile GDF data into a DLL. For detailed steps on how to modify your installer to call into Game Explorer APIs, see the Windows Game Explorer Integration article.