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:

• Introduction to Windows game deployment features in XNA Game Studio 3.0
• Creating an MSI-based installer for the XNA Game Studio 3.0 platformer starter kit
• Creating an installer that includes a Visual Studio bootstrapper package and an MSI built with WiX 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 https://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 https://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 https://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 https://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>

Comments

• Anonymous
  April 13, 2009
  PingBack from http://blogs.msdn.com/astebner/archive/2008/10/31/9027445.aspx

• Anonymous
  January 21, 2010
  Hi aaron! I learn about this with reading some documentation for integrating games to windows games explorer. I've got finish the GDF project with a .rc file, and the executable file is trusted well with a certificate. Now, in the docs says this: it must be encapsulated within a resource section of a binary file (either an executable or DLL) So how can i do this?, i've got installed visual studio 2008. I need to do this to include the binary in a project of installshield like "Installscript MSI Project" and finish to compile and build the installation. thanks

• Anonymous
  January 25, 2010
  Hi Thanatos83 - You should be able to use steps like the ones listed in the above blog post to accomplish this.  I used the GDF Editor tool to create a .rc file, then used rc.exe from the Windows SDK to compile the .rc file into a .res file, then added the .res file to my game project in Visual Studio by using the Resources section of the Application tab in my project's properties page. Can you please give the steps listed in the above blog post a try and see if they work for you as well?

• Anonymous
  January 27, 2010
  Hi aaron! yes, but i have only a binary exe not all the resources of the project. So there is another method to compile this into binary???

• Anonymous
  January 27, 2010
  Hi Thanatos83 - I'm not sure I understand your scenario exactly.  Are you saying that you only have a compiled EXE for your game, but you don't have the source code and build the EXE yourself?  If that is the case, then my understanding from reading the Game Explorer documentation is that you can create your own separate binary file (a DLL or an EXE) and embed the GDF file and the game's icon and thumbnail into this separate binary file.  For additional details about this scenario, I encourage you to take a look at the Game Explorer documentation as well - http://msdn.microsoft.com/library/ee419047.aspx.

• Anonymous
  January 30, 2010
  Hi Aaron! yes, I have only a compiled exe, because this exe was compiled a lot of time and only have this exe and other files that aren't part of resource of executable. I read the documentation and i see the step called: Test with sample code. so this is the way to make my own binary file?, or did you refer another step in this documentation?.

• Anonymous
  January 31, 2010
  Hi Thanatos83 - The step in those instructions that says to test with sample code is talking about testing if you plan to use Game Explorer APIs in your setup program or application.  If you are going to do this, there is a sample solution called GameUXInstallHelper that is available in those MSDN pages that you can use as a starting point. If you only plan to create and embed a GDF file into a binary file, you can create any kind of binary file and use that - for example, just create a blank Win32 application in Visual Studio or something like that.

• Anonymous
  February 13, 2010
  Hi Aaron! So the only way is make other Win32 application and not use my exe??? The requisite of "GameUXInstallHelper" is embed the GDF file into a resource of binary so there isn't posible to use my exe. :S

• Anonymous
  February 14, 2010
  Hi Thanatos83 - I know how to embed a resource file (which you need to do to embed the GDF into the game binary) into a binary when you are building the binary yourself.  I'm not sure if you can do that if you are using a pre-built binary though.  I haven't been able to find any information on MSDN about how to do this.  You may want to ask on one of the Visual C++ forums (http://social.msdn.microsoft.com/Forums/en-US/category/visualc/) whether or not it is possible to embed a new .res file into a binary after the binary has already been compiled.  I'm sorry I'm not able to be more helpful in this particular scenario.

• Anonymous
  February 14, 2010
  OK Aaron so thanks for all and the link of the forum. I'll go there to ask this :)