WixGamingExtension

WiX Toolset

WixGamingExtension

The WixGamingExtension lets you register your application as a game in Windows Vista and later, in three main categories:

  • Game Explorer integration with game definition file
  • Game Explorer tasks
  • Rich saved-game preview

Game Explorer integration

For an overview of Game Explorer, see Getting Started With Game Explorer. Game Explorer relies on an embedded file (game definition file or GDF) to control the data displayed about the game. For details about GDFs, see The Game-Definition-File (GDF) Schema and GDF Delivery and Localization. Using WixGamingExtension, you register a game with Game Explorer using the Game element as a child of your game executable's File element:

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

The Game/@Id attribute is used as the InstanceID attribute discussed here, rather than generating new GUIDs at install time, which would require persisting the generated GUID and loading it for uninstall and maintenance mode.

Implementation note: Using the Game element adds a row to a custom table in your .msi package and schedules the Gaming custom action; at install time, that custom action adds/updates/removes the game in Game Explorer and for operating system upgrades. (See Supporting an Upgrade from Windows XP to Windows Vista for details.)

Game Explorer tasks

In Game Explorer, a game's context menu includes custom tasks:

  • Play tasks start the game with optional arguments.
  • Support tasks start the user's default browser to go to a specific URL.

For details, see Game Explorer Tasks. In WixGameExtension, PlayTask and SupportTask are child elements of the Game element:

<File Id="MyGameExeFile" Name="passenger_simulator.exe" KeyPath="yes">
    <gaming:Game Id="985D5FD3-FC40-4CE9-9EE5-F2AAAB959230">
        <gaming:PlayTask Name="Play" Arguments="-go" />
        <gaming:SupportTask Name="Help!" Address="http://example.com" />
        ...
    ...
</File>

For details, see the Gaming schema documentation.

Implementation note: Game Explorer tasks are shortcuts, so the Gaming compiler extension translates the PlayTask into rows in Shortcuts and SupportTask into WixUtilExtension InternetShortcuts. It also creates directories to hold the shortcuts and custom actions to set the directories.

Rich saved-game preview

Windows Vista includes a shell handler that lets games expose metadata in their saved-game files. For details, see Rich Saved Games. If your game supports rich saved games, you can register it for the rich saved-game preview using the WixGamingExtension IsRichSavedGame attribute on the Extension element:

<ProgId Id="MyGameProgId">
    <Extension Id="MyGameSave" gaming:IsRichSavedGame="yes" />
</ProgId>

Implementation note: The Gaming compiler extension translates the IsRichSavedGame attribute to rows in the MSI Registry table.