Building Game Explorer Support Into Your XNA Project

One of the great new features in Microsoft® Windows® Vista is the Game Explorer. The Game Explorer (or GameUX, as taken from the C++ header file for the component) makes it easy for Vista users to quickly and easily find the game they want to play or administer. Unfortunately, when Microsoft released XNA Game Studio™ Express, support to add XNA projects to Game Explorer was not added. In this article, I will demonstrate how to add support for Game Explorer into your XNA project.

For this article you will require the following software: XNA Game Studio™ Express, the Windows SDK, and the DirectX SDK. If you do not have Visual C++™ Express or better installed, make sure to install the C++ compiler as part of Windows SDK.

There are some caveats with using this method of integration, but until such a time as Microsoft adds Game Explorer support to XNA Game Studio™ Express, this is the only reasonable way to add the integration. See the section called “Problems and Caveats” for details.

Creating a Game Definition File

To begin, you'll need a Game Definition File. A Game Definition File (extension .gdf) is an XML file that provides Vista with the information it displays in Game Explorer, such as game version, ratings (for parental controls), Vista performance ratings, and so on. Included in the DirectX SDK is an application that helps create and manage GDFs for you. The GDF Editor (in the Start Menu at Microsoft DirectX SDK ? DirectX Utilities ? Game Definition File Editor) provides an easy way to edit your GDF, as well as set an icon and thumbnail for your game.

Start off by launching the GDF Editor and create a new project. You can create the project file in the same folder as your game project, but if you wish to create localised editions of your game you may quickly find yourself drowned in subfolders for each different language. Once you've chosen a location for your project and clicked the Save button, GDF Editor lets you name your project and choose languages for localisation. If you're only going to support one language, don't bother checking off any of the languages. If you choose later to localise, you can add new languages later by right-clicking in the sidebar and choosing Add New Language from the context menu.

After you've made it through the localisation dialog, you can finally get to work. GDF Editor automatically opens up the language-neutral pane, and additional localised GDFs can be accessed by expanding the sidebar. Don't worry about the Game ID field; this is used by Game Explorer to identify your game, but you don't need to use it.

The various other fields available define the following:

Game Name
Your game's name as it appears in Game Explorer.
Description
A brief description of your game. Game Explorer doesn't use it, yet, but it might in the future.
Release Date
The day your game goes public.
Saved Games Folder
This tells Game Explorer where saved games are stored. The dropdown lets you choose a base folder for saved games, while the textbox lets you specify from there. If you don't have saves, choose Not Specified. You should not keep saved games in the same folder as your game; see the section called “Save Game Locations” for more information.
Windows Experience Index
This lets you state how powerful a computer should be to be able to run your game. Simple XNA games should be able to make do with a score of 1, but you might want to do some testing to determine what values to put in here.

Beyond these fields, you can also add other information about your game, such as the game genre, developers, and publisher information. You can also set an icon and thumbnail for Game Explorer to display when browsing through games.

Lastly, you can (and should) add the filename of your game executable to the Executables section. When Vista's General Application Restrictions feature is activated, this list of files is checked to make sure that your game is allowed to run. If there are any other programs that your game launches, add them as well. The filenames are relative to the install directory for your game, unless they start with an environment variable.

Unless you are using Authenticode to sign your game, there is no point in adding game ratings. For one, Vista treats all unsigned games as unrated, even if there are ratings information present in your GDF. For another, it may be illegal in places to claim a game rating unless it has actually been granted. While the sample provided with this article has set an ESRB rating, this is only to demonstrate the feature. See the section called “Authenticode Signing” for details.

Once you've filled out all the details for the language-neutral pane, make sure to do the same for each language you've chosen for localisation. Note that the Windows Experience Index and ratings fields cannot be set on localised panes; this information is taken from the language-neutral pane only. Finally, your GDF is done!

Adding Resources To Your XNA Project

Once you've put together your GDF, it's time to add it to your assembly. This stage is a bit tricky, as it involves some mucking about with your project file.

We'll start off by generating a .rc file in the GDF Editor. While your GDF project is open, go to Resources ? Build Script for Project. This will generate both a C++ header and a .rc file for your project, with the same name as your project (i.e. project TestProject results in TestProject.h and TestProject.rc). GDF Editor doesn't support command-line generation of these files, so you'll have to make sure you create them every time you make changes to your GDF project.

Once your .rc and .h files have been created, it's time to compile them into a .res file. Start off by opening the command prompt, and run vsvars32.bat (if you have Visual Studio™ 2005 Standard or better installed) or SetEnv.Cmd (if you are using the Windows SDK). Make sure to change the paths to match the actual locations of these files.

At this time, the environment variables needed to run the resource compiler should be set. If you used vsvars32.bat ensure that the %INCLUDE% environment variable has the Windows SDK include directory in it, or execute the following to add it (making sure that the path is correct):

set INCLUDE=C:\Program Files\Microsoft SDKs\Windows\v6.0\Include;%INCLUDE%

Once this path is properly set, change the current directory to the same one as your .rc and .h files. Run the rc command, passing to it the name of the .rc file. It should generate a .res file with the same name as the .rc file (continuing the previous example, from TestProject.rc you should get TestProject.res). If rc complains about not finding gameux.h then your %INCLUDE% environment variable is not properly set. Make sure to add the Windows SDK include directory in it.

Finally, you're ready to modify your project file and add your GDF resources to your game. This step cannot be done via the Visual Studio™ IDE, but only by modifying your project's .csproj file. The modification is small and simple, but it's easy to change your project file in such a way that it no longer works. Before doing this step, make a backup copy of your project file.

C# project files are XML files used by MSBuild (the .NET equivalent of make) to manage and compile your game. Despite the complex look of the file at first glance, the contents of a project file are actually quite simple. Project properties are kept in <PropertyGroup> blocks, and both references and files are kept in <ItemGroup> blocks. The names of tags inside propery group blocks are also the property names, and the names of tags inside item group blocks define what group the item belongs to.

For our purposes, we only need to add a single property, Win32Resource, to the default property group. This group should be at the top of the project file, and can be identified as the first <PropertyGroup> block without a Condition attribute. At the bottom of the block, before the closing tag, add the following XML code:

<Win32Resource>filename.res</Win32Resource>

The Win32Resource property controls the value passed when using the /win32res option with the C# compiler. This way, .NET applications with custom Windows resources can have such resources included in the compiled executable. However, using it also comes with some cost. See the section called “C# Compiler and Windows Resources” for details.

Once you've set the property in the project file, build your project. If you edit the project file while Visual C#™ Express is still open, it will prompt you to reload the project. Make sure that you do so! After the project has been successfully built, open your game executable with a resource viewer (such as PE Resource Explorer by Colin Wilson). There should be a DATA type resource named __GDF_XML, and if you included a thumbnail, another DATA type resource named __GDF_THUMBNAIL.

Registering With Game Explorer

At this point, you'll have a final executable with all the resources Game Explorer needs built right in. Which brings us to our final task – the actual registration of the game. This stage is generally done by an installer such as Inno Setup or InstallShield rather than by the user or developer directly. But to demonstrate how a game is registered and what additional files are created, let's walk through the process.

Before actually registering the game, install everything that goes on the hard drive. If you don't do this, after registering you might find that you can't access the game's location. We don't actually bother with that in the RegisterGame sample, but that's because it isn't really an installer, after all. Once all the game files have been copied to the hard drive, it's time to actually hook up with Game Explorer. The RegisterGame sample included with this article demonstrates the use of GameuxInstallHelper.dll, a sample library that comes with the DirectX SDK to demonstrate how to do all the registration work.

Game Explorer is able to work with games installed as per-machine and per-user, simultaneously. To tell apart installations of games, the first thing you need to do is generate a Instance ID. While you can have Game Explorer generate one for you when you're dealing with it directly, the GameuxInstallHelper library provides a GenerateGUID function, or you can use Guid.NewGuid() to create one yourself. Beyond actually registering and tracking the game, this value is necessary for setting up task links.

Next, we will actually register the game itself. The AddToGameExplorer function requires the location of your game's .exe file, the folder in which the game is installed, a value stating whether it is a per-machine or per-user installation, and the instance ID. If you examine GameuxInstallHelper.cs in the RegisterGame sample, you'll notice the GameInstallScope enumeration; this is what is used to tell Game Explorer whether the game is accessable to just the user installing it, or all the users on the computer. Once the game is registered, you can also register it with Media Center. This is left out in the sample, but the functions for it are still in the project and can be used if wanted.

Now, we can set up the task links that appear in Game Explorer. Tasks are simply shortcuts that reside in a certain folder. They are divided into play tasks and support tasks, and while you can have an unlimited number of either type of task, Game Explorer will only show the first few of each type. For each task you create, you can specify the name, the program and program options (the Target value in a shortcut), and the order in which it is listed. Note that the first play task (the one with an order number of 0) is always called "Play" despite whatever name you want to give it. Along with ordinary shortcuts, you can also provide URL links for tasks. Rather than pass the path to an executable or data file, use the URL for a website when using the CreateTask function.

When uninstalling a game, don't simply do things in reverse order. Before anything else, try to unregister the game from Game Explorer. This may or may not fail, but if it does fail, you'll do your players no good by simply removing the task links and program files while still leaving the game itself to appear in Game Explorer. Once you've unregistered it, then remove tasks, files, and the Media Center registration.

Conclusion

By now, you should have an XNA based game that integrates with the Vista Game Explorer. However, there are still improvements which can be made. For example, with good knowledge of MSBuild, it should be possible to integrate parts of the resource building process into the overall build process. You could also work on solving the missing version resource problem. Or including game registration in your favourite installer system!

For more information on how to use the Game Explorer, please read the Game Explorer documentation on MSDN. Other useful documents include the DirectX SDK technical articles, especially those dealing with game installation.

The Demo Projects

Two projects are included with this article. TestProject demonstrates the addition of the GDF resources to an XNA game project. RegisterGame demonstrates the use of the GameuxInstallHelper sample from the DirectX SDK and shows how to register a game with Game Explorer.

To build TestProject, first open TestProject.GDFMakerProject and generate the resource files as described in the section called “Adding Resources To Your XNA Project”. Next, in Explorer, drag the newly created TestProject.rc onto buildres.bat. Once it has built TestProject.res you can actually build TestProject itself.

As long as TestProject builds, so should RegisterGame. RegisterGame provides a few options that you can play with on the command line, but rather than detail them here, I'll suggest that you read the source and see what's possible for yourself.

Problems and Caveats

There are a number of potential problems with integrating XNA applications into the Game Explorer.

C# Compiler and Windows Resources

By default, the C# compiler creates a version resource for executables and DLLs that it generates, based on certain attributes (normally set in AssemblyInfo.cs). As well, any icon file set with the /win32icon option (in MSBuild, the ApplicationIcon property) is used to generate an icon group resource for executables and DLLs. However, when using the /win32res (MSBuild, Win32Resource), the compiler does not generate either of the default resources.

To work around the icon problem, simply add your project's icon file to your GDF project via the GDF editor. This will ensure that the icon is included when generating the .res file. At this time there is no provided workaround for the version resource.

Another potential issue when building is when both /win32icon and /win32res are specified. The C# compiler will quit with error CS1565 when this occurs. To fix the problem, unset the application icon in the IDE, or remove the ApplicationIcon in the project file.

Locked Out During Registration

Registering a game and setting up tasks can fail when not managed carefully. On systems where parental controls are activated, access to the installation directory may be blocked if the installing user does not have rights to play games of the same rating as the game being installed. While this may not be an issue most of the time, it is important to make sure that all game files are installed before registering the game. It is also a very good idea to not register the game in your build directory, but to another directory instead.

Authenticode Signing

Vista uses Authenticode signing to ensure that a game's content rating is legitimate. As an unsigned game could be easily modified to change an AO rating to EC, thus defeating parental controls, an unsigned game is always treated as unrated even when ratings information is provided. As well, patches meant to be applied by users with limited user accounts must be Authenticode signed.

There are several different certificate authorities from which you can recieve a digital certificate to use for Authenticode signing applications, and tools are provided in the Windows SDK that allow you to create your own certificates. However, creating your own may not work on other computers, and you are advised to acquire a certificate from a recognized certificate authority if you wish to support content ratings and limited user accounts.

Save Game Locations

XNA games should not store saved games in the same folder as the game itself, especially if the game is installed per-machine as opposed to per-user. Unless the player has administrative rights on the computer that the game is installed upon, he or she will have difficulties with both saving and loading, due to access control settings in Vista. Fortunately, the XNA Framework is able to supply a standard location for saved games that should be used instead.

Known as user storage in the XNA Framework documentation, this location is placed within the user's My Documents\SavedGames folder, classified by both a programmer-supplied title string and by a PlayerIndex value. The following function will return the path to user storage, after which you can deal with folders and files with the standard System.IO classes:

public static string GetUserStorage (string title, PlayerIndex player)
{
    // If your game is cross-platform, use the asychronous methods
    // BeginShowStorageDeviceGuide and EndShowStorageDeviceGuide on the
    // Xbox360 to avoid crashing or hanging your game.
    StorageDevice device = StorageDevice.ShowStorageDeviceGuide(player);
    StorageContainer container = device.OpenContainer(title);
    return container.Path;
}

Note that Vista provides a different standard location for saved games, which is not the same as the location which the XNA Framework uses. Later versions of the XNA Framework may support the Vista save location, but in the meantime you'll need to access it directly without the support of the storage classes. If you choose to use the XNA-set location for save games, you should choose My Documents as the base directory, with SavedGames\TitleLocation as the specific location (where TitleLocation is replaced with the actual title string used with the storage classes).

XNA Game Studio Express 1.0 Refresh

The changes in the the 1.0 Refresh version of XNA Game Studio™ Express do not affect anything in this article. Despite the addition of a game thumbnail to projects, it seems that this is used only for transferring games to the Xbox360 or when packaging games to send to other XNA developers, and not added to the game executable itself.

An interesting addition with the 1.0 Refresh is the xnapack.exe tool. This program creates special packages (.ccgame files) that can be shared with other XNA Game Studio™ Express users. These packages include the executable and asset files of a game project, for either Windows or Xbox360 platforms, and can serve as a quick and dirty way of distributing your game project. However, these packages can only be used by people who have XNAGSE already installed on their computers, and installing a game using these packages does not register the game with Game Explorer.

References & Additional Resources

Microsoft Game Technology Group. Windows Game Explorer for Game Developers. December 2006.

Microsoft Game Technology Group. Authenticode Signing for Game Developers. December 2006.

Microsoft Corporation. XNA Website.

Creative Commons License
Building Game Explorer Support Into Your XNA Project by Christopher S. Charabaruk is licensed under a Creative Commons Attribution-No Derivative Works 2.5 Canada License. Demo source code is released into the public domain.

AttachmentSize
Demo source89.87 KB
Demo binaries59.57 KB
Posted In