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?
- Windows Installer is the package manager for Windows. MSI files are its
- 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 ;-)
- WiX is powerful, easy to read and allows access to all major features of MSI.
- WiX is free.
- WiX files are human-written, human-readable text files.
- WiX comes as several small simple binaries.
- There's loads of simple (although occasionally confusing) documentation about WiX out there.
- WiX 3.5
- Windows SDK 7.1 (for signing)
While the template may work for other versions, it won't do so unless modified.
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
Where to put files
game.wxs expect to find the final directory structure
dist in your project's root. (And the root should be exactly one folder
Things to replace
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
buildmsi.bat and replace the project-specific
information. The following appears in both files in multiple locations:
SkuNameShortused in this project. Also the name of the main executable (
minigame.exe). If your game is called
Eternal Sword Extreme Deluxe, replace
esword-edin both files and name your main executable
Mini Game- the
SkuNameused in this project. If your game is called
Eternal Sword Extreme Deluxe, replace
Mini Gamewith 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.
game.wxs and the various
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.wxsto determine which icon will be used for e.g. Add/Remove Programs.
There are several hardcoded occurrences of
1033. This defines
(United States) locale. Change that if you want to.
On building MSI
Having prepared everything in
dist, simply run
buildmsi.bat will move your main executable out of the
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
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.
To sign the executable and the MSI file, edit
the certificate file, specify the certificate password and specify the
timestamping server. Then, uncomment everything marked with
If you are okay with having administrator privileges, skip this.
Privilege requirements are set by several attributes:
<Package InstallPrivileges="..."/>- either
elevated, this explicitly sets either requiring the administrative or non-admin privileges. WiX documentation says this is for Vista and later.
<Package InstallScope="..."/>- either
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
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
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 - <firstname.lastname@example.org>