Thoughts about setup and deployment issues, WiX, XNA, the .NET Framework and Visual Studio
All postings are provided AS IS
with no warranties, and confer no rights. Additionally, views expressed
herein are my own and not those of my employer, Microsoft.
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:
How to use the updated sample
To build and try out this updated sample, you can use the following steps:
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:
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:
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:
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:
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:
For reference, the Resource File radio button ends up adding the following information to your game’s .csproj file:
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:
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>
PingBack from http://blogs.msdn.com/astebner/archive/2008/10/31/9027445.aspx
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.
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?
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???
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.
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?.
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.
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
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.
OK Aaron so thanks for all and the link of the forum. I'll go there to ask this :)