Update: release 1.2.2 of panda contains a nonfunctioning copy of packpanda. To repair it, install panda, then move "packpanda.nsi" from the subdirectory "direct" to the subdirectory "direct\src\directscripts." This will be permanently fixed in the next release.

---

Packpanda is a utility that lets you create a windows installer for a panda game. The result looks like any other windows installer:

When the installation is done, the end-user will find your game in his start menu:

The end-user doesn't need to have a copy of panda. He doesn't even need to know that he is using panda. He just installs the game and plays it.

Files that your Game should Contain

Before you pack up your game, you need to put all of your game files into a single directory (which may have as many subdirectories as you desire). This directory will be packed up and shipped to the user, along with the panda runtime system. Your game directory needs to contain several files:

main.py. This is your main program. When the user clicks on the start-menu entry for the game, this is the file that will get executed.

installer.bmp. This image will appear on the installer screen. If present, it must be a 164x314 windows BMP file. This file is not required.

license.txt. This is your game's software license. The file, if present, must be plain ascii. The game's license will appear inside the installer, and will also be copied to the game's installation directory. Of course, your license only covers the code that you wrote, not panda itself, which is covered by the panda license. The license file is not required.

icon.ico. This is your game's icon, which will appear in the start menu. If you don't supply an icon, the panda icon will be used instead. This file is not required.

Packing up your Game

The command to pack up your game is "packpanda", and you must specify the "--dir" command line option to tell it the name of the directory containing your game. Packpanda will immediately analyze your game and print out a status report:

In this example, packpanda has inferred that the name of the game is "Airblade," based on the directory name. It plans to install the game into "C:\Airblade", and to add the start menu folder "Airblade". It plans to call the installer "Airblade.exe". Later, we will tell you how to override some of these defaults.

As you can see, packpanda is looking inside the game directory for the files mentioned above: main.py, installer.bmp, icon.ico, and license.txt. It notes that some of those files are "missing", which is not a problem. The only file that is required is main.py.

Packpanda can clean up your source tree before shipping it. When doing so, packpanda never modifies your original copy of the game. Instead, it copies the game to a temporary directory, as seen above.

EGG Verification and PY Verification

Packpanda will check all of your EGG and PY files to make sure that they compile correctly. It checks EGG files by running them through egg2bam. It checks PY files by running the python compiler on them. If any file fails, the game will not be packed.

Packpanda can optionally ship the BAM and PYC files it creates to the end-user. To ask it to do so, use the following command-line options;

These command line options do not remove the corresponding EGG and PY files from the distribution. If you wish to remove EGG and PY files, you need to use the --rmext option, documented below.

When packpanda generates a BAM or PYC file, it puts it in the same directory as the corresponding EGG or PY file. If an EGG file contains a texture path, then the generated BAM will contain a relative texture path that is relative to the game's root directory. Packpanda makes sure that your game's root directory ends up on the model path.

If you do not supply the --bam or --pyc options, packpanda will still generate BAM and PYC files for verification purposes, but it will not ship the files it generates to the end-user.

Stripping Files from the Distribution

Often, your master copy of a game contains files that should not be shipped to the end-user. For situations like this, packpanda contains command-line options to strip out unnecessary files:

These options are particularly useful in several common situations:

To remove CVS directories: packpanda --rmdir CVS

To ship BAM instead of EGG: packpanda --bam --rmext egg

To ship PYC instead of PY: packpanda --pyc --rmext py

Changing the Game's Name

Normally, packpanda infers the game's name to be the same as the directory name. That isn't always convenient, especially when the game has a long name. The following command line option allows you to tell packpanda the name of the game:

This string will show up in a number of places: in particular, throughout the installation dialogs, and in the start menu.

Version Numbers

If you wish, you can assign your game a version number using this command line option:

The only thing this does is to add "X.Y.Z" to the install directory and to the start menu item. That, in turn, makes it possible for two versions of the same game to coexist on a machine without conflict.

Compression Speed

Normally, packpanda uses a very good compression algorithm, but it's excruciatingly slow to compress. You can specify this command line option to make it go faster, at the cost of compression effectiveness:

Moving Beyond Packpanda

Packpanda has a lot of limitations. However, packpanda is actually a front end to NSIS, the "Nullsoft Scriptable Install System." NSIS is incredibly powerful, and very flexible, but unfortunately rather complicated to use. Packpanda hides all that complexity from you, but unfortunately, in so doing, it limits your options.

If you find yourself outgrowing packpanda, one sensible thing to do would be to learn how to use NSIS directly. This is an easy transition to make. The first step is to simply watch packpanda in action. It will show you all of the commands it is executing. You can then copy those commands into a batch file. If you run that batch file, you're executing NSIS directly.

Once you have direct control over NSIS, you can begin editing the NSIS command-line options and the NSIS configuration file (packpanda.nsi). Of course, to do so, you'll need to first read the NSIS manual (available on the web). From that point forward, you have unlimited flexibility.