Skip to Content

New WiX feature: Gaming extension

Posted on

The Game Explorer is a new feature in Windows Vista to collect and richly present installed games. Game Explorer is a shell folder that includes detailed information about each game, including box art, content ratings (and parental-control restrictions based on them), and performance requirements (using the Vista performance rating system).

Most of the details shown in Game Explorer come from the game developer in the form of the Game Definition File (GDF) that’s embedded as a resource in your executable. Details and samples on the GDF and Game Explorer are available in the DirectX SDK, especially in Getting Started with Game Explorer.

The WiX Gaming extension is a compiler extension with custom actions to do the following:

  • Register a game in Game Explorer.
  • Create tasks in the context menu of a game in Game Explorer.
  • Register a game on Windows XP so it’s available in Game Explorer after an upgrade to Windows Vista.
  • Register extensions with support for the rich saved-game preview handler.

[Update: WixGamingExtension will be available in the next weekly release of WiX v3.]

Registering games

To register a game, add a Game element and specify its instance ID in its Id attribute as a child of the File element for the game executable. For example:

<File Id="MyGameExeFile" Name="passenger_simulator.exe" KeyPath="yes"><br /> <gaming:Game Id="985D5FD3-FC40-4CE9-9EE5-F2AAAB959230"><br /> ...

The DirectX SDK suggests letting the Game Explorer COM object create a new GUID for every installation. It then suggests writing the new GUID to the registry or file system to persist it or to use WMI to query Game Explorer for the GUID. The prior release of Flight Simulator used WMI, which was a fairly regular source of failures during uninstall and repair operations. Following the mantra of minimizing runtime dependencies during setup, I chose to let the setup author specify a static ID. No persistence or runtime dependencies required.

Creating tasks

Game Explorer tasks are simply shortcuts shown on the context menu on the game icon in Game Explorer. Play tasks are plain ol’ shortcuts to the game executable with optional command-line arguments. Support tasks are shortcuts to URLs. The shortcuts must be created in specific directories for Game Explorer to find them.

WixGamingExtension translates strongly-typed PlayTask elements into rows in the Shortcut table; the Name attribute is the name of the shortcut and Arguments are the command-line arguments. WixGamingExtension translates SupportTask elements into WixUtilExtension InternetShortcuts; the Name attribute is the name of the shortcut and Address is the URL.

<File Id="MyGameExeFile" Name="passenger_simulator.exe" KeyPath="yes"><br /> <gaming:Game Id="985D5FD3-FC40-4CE9-9EE5-F2AAAB959230"><br /> <gaming:PlayTask Name="Play" /><br /> <gaming:PlayTask Name="Play in Deity Mode" Arguments="-deity" /><br /> <gaming:SupportTask Name="Help!" Address="<a href="http://example.com">http://example.com"</a> /><br /> <gaming:SupportTask Name="Cheat codes" Address="<a href="http://example.com">http://example.com"</a> /><br /> <gaming:SupportTask Name="Get P0wned" Address="<a href="http://example.com/1337">http://example.com/1337"</a> /><br /> <gaming:SupportTask Name="Get owned" Address="<a href="http://example.com/non1337">http://example.com/non1337"</a> /><br /> <gaming:PlayTask Name="Show no mercy" Arguments="-cutenfluffy" /><br /> <gaming:SupportTask Name="Forums" Address="<a href="http://example.com">http://example.com"</a> /><br /> </gaming:Game>

Registering for OS upgrades

When you install a game on Windows XP and later install Windows Vista as an upgrade, the Vista upgrade can automatically register the game in Game Explorer. All that’s required is writing the task shortcuts and a few registry values. WixGamingExtension does that automatically; no extra authoring is required.

Rich saved games

Vista includes a special preview handler for file extensions registered as a saved-game file. Most of the effort required to support rich preview is in the game itself; the burden on setup is just to register the extension for the preview handler. WixGamingExtension supports this registration as a simple yes/no attribute on the standard WiX Extension element:

The gaming extension is part of the work I’m undertaking to convert ACES Studio’s products from our old script-based installer to a declarative installer built with WiX. Studio management was pleased to contribute the work to the wider WiX community.

If you happen to publish a cool game that uses WixGamingExtension, feel free to send a copy my way. 😀