HTTPS SSH

ivucica's WiX Template for Games

This is a simple template for using Windows Installer XML to create installers for games. While WiX itself is quite simple and easy to use, there are still some gotchas.

For example, it's helpful to keep EXE separate from the rest of the data files. From the main script, you want to refer to the main executable, but you want to list the rest of the data files automatically.

You may also want to do some code signing of the executable or the MSI, as is required with one online store. (In fact, this template is based on work done to distribute some games in the Intel AppUp store.)

The games that this template was produced for were packed over two years ago. I've removed the company branding, I've regenerated GUIDs so you don't accidentally reuse them (that would be very bad) and I've written a small demo program that is not really a game, but that you can build and see how the project should be structured and how the installer will behave.

The template could certainly be used for non-games as well, or it could be used as a basis for non-games. It is, however, not designed for anything but installation of games that use little to no features of Windows. No license agreement is displayed, intentionally; it is presumed that the user has accepted the agreement in some other way.

Based on the requirements for the online store the template was designed for, exactly one shortcut is created in the root of the start menu. Also, the installer explicitly requires administrator privileges.

Why use MSI and WiX?

  1. Windows Installer is the package manager for Windows. MSI files are its .deb files.
  2. MSI files are used on Windows domains. So if your game has to be mass-deployed to a thousand machines, the administrator that has to do it shall be quite pleased with your distribution mechanism ;-)
  3. WiX is powerful, easy to read and allows access to all major features of MSI.
  4. WiX is free.
  5. WiX files are human-written, human-readable text files.
  6. WiX comes as several small simple binaries.
  7. There's loads of simple (although occasionally confusing) documentation about WiX out there.

Requirements

  • WiX 3.5
  • Windows SDK 7.1 (for signing)

While the template may work for other versions, it won't do so unless modified.

Concepts

In the template, several terms are used:

  • SkuName - full name of your game; used, for example, in Windows' Add/Remove programs and in other places
  • SkuNameShort - lowercase, spaceless, short name of your game; used, for example, as the name of your main executable
  • GUID - globally unique identifier; standardized, specially formatted strings used in identifying various items in MSI files. Each project should have a unique, constant identifier for the UpgradeCode

Where to put files

buildmsi.bat and game.wxs expect to find the final directory structure in dist in your project's root. (And the root should be exactly one folder above buildmsi.bat and game.wxs.)

Things to replace

Before running buildmsi.bat, don't forget to make your project unique! Very unique! As in, don't even think of distributing a project with the UpgradeCode GUID that I shipped the template with.

(And don't change UpgradeCode, ever.)

Now, edit game.wxs and buildmsi.bat and replace the project-specific information. The following appears in both files in multiple locations:

  • minigame - the SkuNameShort used in this project. Also the name of the main executable (minigame.exe). If your game is called Eternal Sword Extreme Deluxe, replace minigame with esword-ed in both files and name your main executable esword-ed.exe
  • Mini Game - the SkuName used in this project. If your game is called Eternal Sword Extreme Deluxe, replace Mini Game with that.
  • Ivan Vucica - my name. Replace with your company name

Note! These all appear in fileproperties.rc. But, since that is a solely example project file, you probably will not be copying that, instead opting for creating it from scratch in your IDE.

Now, edit game.wxs and the various <?define?> tags.

  • SkuNameShort - read above for explanation; this should be the main exe name
  • SkuName - read above for explanation; this should be the full game name
  • ProductVersion - Windows Installer uses first three digits and ignores the fourth one (if present) when determining whether two versions are the same
  • Manufacturer - read above for explanation; this should be the company name
  • ProductCode - while you could generate a new GUID, you can also let WiX produce one for you by leaving this as '*'.
  • UpgradeCode - generate this GUID once, and ensure it is unique for your game. This is used in determining whether the existing package should be uninstalled and replaced with the new MSI
  • Keywords - enter some keywords describing your game
  • ShortcutComponentCode - generate a GUID. Not sure if this could be '*'.
  • HelpLink - displayed in Add/Remove Programs
  • Homepage - displayed in Add/Remove Programs
  • IconFile - used in several places in game.wxs to determine which icon will be used for e.g. Add/Remove Programs.

There are several hardcoded occurrences of 1033. This defines English (United States) locale. Change that if you want to.

On building MSI

Having prepared everything in dist, simply run buildmsi.bat

buildmsi.bat will move your main executable out of the dist folder. Then it'll build a list of all game data files, support .dlls and whatever else you may have thrown in the dist folder. Then, the main executable will be put back into the dist folder, and the main MSI build will commence.

Once the msi has been produced, you could try the experimental buildexe.bat. The produced exe doesn't seem to work quite right, though, once the product has been already installed.

On signing

To sign the executable and the MSI file, edit buildmsi.bat, specify the certificate file, specify the certificate password and specify the timestamping server. Then, uncomment everything marked with Uncomment if signing.

On privileges

If you are okay with having administrator privileges, skip this.

Privilege requirements are set by several attributes:

  • <Package InstallPrivileges="..."/> - either limited or elevated, this explicitly sets either requiring the administrative or non-admin privileges. WiX documentation says this is for Vista and later.
  • <Package InstallScope="..."/> - either perMachine or perUser, this decides where the package should be installed and under what privileges.

You can ignore <Package AdminImage="..."/> property; this seems to relate to an install scenario used in large corporations with extremely large MSIs.

Before removing the admin privileges requirement, note that while the installbase might increase, you'll have to modify the script to install to another location (because %ProgramFiles% is probably not writable by a non-admin user!), possibly providing UI for changing the destination folder.

Support, warranty, etc.

I provide absolutely no warranty for this set of files. By using these, you agree that you won't hold me responsible for any damage you cause to your (or other) machines through using the template.

I will not be customizing the template much further, and whatever question you have on WiX or MSI, I probably can't answer it timely or satisfactory. This template and this readme talk about practically everything I have to say about WiX.

Please understand that the majority of work on this was done almost two years ago, so I cannot help a lot.

But if you greatly desire to relay your thoughts to me, use my email address.

Ivan Vučica - <ivan@vucica.net>