Creating an MSI-based installer for an XNA Game Studio game that integrates with Windows Game Explorer

I’ve previously written a few posts about how to get started with Windows game deployment for games created with XNA Game Studio 3.0:

The next thing I want to demonstrate is how to add Windows Game Explorer integration to your XNA Framework-based Windows game.  For this demonstration, I’m going to build on the sample installer for the XNA Game Studio 3.0 platformer starter kit that includes a Visual Studio bootstrapper (described in this blog post).

Updated sample that builds an MSI and a bootstrapper that integrates with Windows Game Explorer

I have posted an updated sample at http://cid-27e6a35d1a492af7.skydrive.live.com/self.aspx/Blog%7C_Tools/WiX%20Samples/wix%7C_sample%7C_xgs30%7C_game%7C_with%7C_bootstrapper%7C_and%7C_gdf.zip that extends my previous sample.  You can use it to create a bootstrapper and an MSI for the Platformer Starter Kit that will integrate the game with Windows Game Explorer during installation.

It includes the following additions/changes from the previous sample:

  • The GDF folder contains the source files, a native resource script named Platformer1.rc, and a compiled native resource file named Platformer1.res that include the GDF file needed to integrate the Platformer Starter Kit with Windows Game Explorer.

    Note – I am not an expert regarding GDF file syntax, so I created a fairly simple GDF file using the GDF File Editor tool that ships in the DirectX SDK for the purposes of this sample.  For more advanced scenarios, please refer to the MSDN documentation for the GDF file schema and the GDF file editor.

  • The file Platformer.wxs has been updated to include <Game/>, <PlayTask/> and <SupportTask/> elements that are a part of the WixGamingExtension.  These elements will cause custom actions to be added to the MSI that will call Game Explorer APIs during installation and uninstallation.

  • The file build_wix_sample_xgs30_game.bat has been updated to add references to the WixGamingExtension to the Candle and Light command lines so that WiX will be able to successfully build the MSI with the new elements that have been added to Platformer.wxs.

How to use the updated sample

To build and try out this updated sample, you can use the following steps:

  1. Install Visual Studio 2008 or Visual C# 2008 Express Edition and XNA Game Studio 3.0.
  2. Install the latest build of WiX v3.0 from http://wix.sourceforge.net/releases/.
  3. Open Visual Studio and create a project using the Platformer Starter Kit (3.0) project template that is included as a part of XNA Game Studio 3.0.
  4. Download the sample from http://cid-27e6a35d1a492af7.skydrive.live.com/self.aspx/Blog%7C_Tools/WiX%20Samples/wix%7C_sample%7C_xgs30%7C_game%7C_with%7C_bootstrapper%7C_and%7C_gdf.zip.
  5. Create a sub-folder named Setup in the Platformer game project that you created above.
  6. Extract the contents of the Setup sub-folder in wix_sample_xgs30_game_with_bootstrapper_and_gdf.zip to the Setup folder created in step 5.
  7. Create a sub-folder named GDF in the Platformer game project that you created above.
  8. Extract the contents of the GDF sub-folder in wix_sample_xgs30_game_with_bootstrapper_and_gdf.zip to the GDF folder created in step 7.
  9. Open this copy of the Platformer Starter Kit in Visual Studio 2008 or Visual C# 2008 Express Edition, right-click on the Windows version of the game project in the VS Solution Explorer and choose Properties.
  10. In the Application tab, go to the Resources section and change select the radio button labeled Resource File.
  11. Browse to the file Platformer1.RES that is located in the GDF sub-folder that you created and extracted in steps 8-9 above.
  12. Save all of your project files.
  13. Build the x86 release version of the project.
  14. Run the script named build_wix_sample_xgs30_game.bat from the Setup folder to build an MSI and a bootstrapper setup.exe for the game.

After doing the above, you can copy setup.exe and wix_sample_xgs30_game.msi from the Setup sub-directory to a server and run setup.exe to install your game and its prerequisites on another computer.  If you install the game on Windows Vista or Windows 7, you can go to Game Explorer (the Games folder on the Start menu) after installation, and you will see a shortcut there for the Platformer Starter Kit.  You can use this shortcut to play the game and/or view support information.  The shortcut will be removed from Game Explorer when you uninstall the game.

How to implement Windows Game Explorer integration – general steps

At a high-level, the steps required to implement Game Explorer integration for a Windows game are the following:

  1. Create a Game Definition File (GDF) with the appropriate information for your game
  2. Embed the GDF file as a resource in one of the binaries that is a part of your game
  3. Include logic into your installer to call Game Explorer APIs to register your game

How to implement Windows Game Explorer integration – XNA Framework-specific details

The Game Explorer APIs require that the GDF file be embedded as a native resource in order to correctly integrate with Windows Game Explorer.  An XNA Framework game is written in managed code, and native resources cannot be directly embedded into a managed binary without some additional steps.  To work around this, you can do one of the following:

  1. Create a stub native binary that includes the GDF file as a resource, and then include this native binary in your game installer
  2. Build a native resource file and embed it into one of your managed game assemblies

For this example, I will use option #2 above.  As a result, there are a couple of additional steps that are required to include Game Explorer integration for an XNA Framework-based Windows game.  The steps look like the following:

  1. Create a Game Definition File (GDF) and native resource script (RC) file
  2. Build a native resource (RES) file from the RC file
  3. Embed the GDF file into one of your game binaries
  4. Include logic into your installer to call Game Explorer APIs to register your game

See below for more details about how to accomplish each of these steps.

1. Create a Game Definition File (GDF) and native resource script (RC) file

To create a GDF file, you can use the Game Definition File Editor that ships in the DirectX SDK.  The GDF Editor tool will create a file name *.GDFMakerProject, which will store the settings used to create the GDF file.  You can use this file to open the GDF project in the GDF Editor and make changes to the settings in the GDF file later on if needed.

The Build Script for Project command in the GDF Editor will create a native resource script file (named *.rc) that you can use to compile a native resource file (named *.res) to embed into one of your game binaries in the next step.

2. Build a native resource (RES) file from the RC file

In order to embed a GDF file into an XNA Framework game binary, you must first build a native resource (RES) file from the native resource script (RC) file that is generated by the GDF Editor tool described in step 1.  You can use the native resource compiler rc.exe that ships in the Windows SDK to compile an RC file into a RES file.  There is detailed information about RC.exe in this MSDN topic.

Here are steps you can use to build a RES file from an RC file by using rc.exe:

  • Open a Visual Studio 2008 Command Prompt
  • Run this command line:  rc.exe /r <full path to your *.rc file>

This command line will create *.RES in the same path as *.rc.

If you only have Visual C# 2008 Express Edition, you will not have a VS 2008 Command Prompt shortcut.  You will need to manually run rc.exe from the Windows SDK directory (by default, this is located at %ProgramFiles%\Microsoft SDKs\Windows\v6.0A\bin after installing Visual C# 2008 Express Edition).

You could also add the rc.exe command line as a pre-build step in your game project if you would like to build the RES file each time you build your game project.

3. Embed the GDF file into one of your game binaries

Once you have built a RES file that includes the GDF file for your game, you need to embed the RES file into one of the managed binaries that is a part of your game.  You can use the following steps in the Visual Studio IDE to accomplish this:

  • Open your game project in Visual Studio 2008 or Visual C# 2008 Express Edition, right-click on the Windows version of the game project in the VS Solution Explorer and choose Properties.
  • In the Application tab, go to the Resources section and select the radio button labeled Resource File.
  • Browse to the file *.RES that you built with rc.exe in step 2 above.
  • Save all of your project files.
  • Rebuild your game – the RES file (and therefore the GDF file) will now be embedded into your main game executable.

For reference, the Resource File radio button ends up adding the following information to your game’s .csproj file:

<Win32Resource>MyResourceFile.RES</Win32Resource>

4. Include logic into your installer to call Game Explorer APIs to register your game

Once you have added a native resource (RES) file that includes your Game Definition File (GDF) to one of your game binaries, you need to add information to your installer to call Game Explorer APIs to register your game with Windows Game Explorer.  The instructions for how to call these APIs is described in more detail in this MSDN topic.  As you can see by looking at that MSDN topic, these instructions are fairly long and involved.  Fortunately, if you are using WiX v3.0 to create an MSI-based installer for your game, you can use the built-in WixGamingExtension to easily include custom actions to accomplish the steps listed in that MSDN topic.

You must add the following information to your WiX authoring to include Game Explorer integration custom actions in your MSI:

  • Add a <Game/> element that is a child of the <File/> element that you embedded the RES file into in step 3 above.
  • Add a <PlayTask/> element that is a child of the <Game/> element.  This will register a command that will be run to play your game from Windows Game Explorer.
  • (optional) Add a <SupportTask/> element that is a child of the <Game/> element.  This will register a command that will launch a support web site for your game if the user selects the Community and Support option from Windows Game Explorer.

For a specific example of this WiX authoring, refer to the <File/> element for Platformer1.exe in Platformer.wxs in the sample at http://cid-27e6a35d1a492af7.skydrive.live.com/self.aspx/Blog%7C_Tools/WiX%20Samples/wix%7C_sample%7C_xgs30%7C_game%7C_with%7C_bootstrapper%7C_and%7C_gdf.zip.

<update date="4/14/2009"> Updated the text to refer to Windows Game Explorer instead of Windows Vista Game Explorer because the above sample will work on Windows 7 as well. </update>