Note: In version 1.6.0, support was added for Linux. Before this version, you will only be able to use packpanda on a windows system.

Packpanda is a utility that lets you create an automatic self-extracting installer for a Panda3D game. On linux, it is capable of creating an .rpm or .deb package. On Windows, it creates an installation wizard, that will look like this:

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. Windows only. 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. Windows only. 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. On Windows, it will install the game into "C:\Airblade", and to add the start menu folder "Airblade". It plans to call the installer "Airblade.exe" (append .rpm or .deb for linux). 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.

Automatically generating BAM and PYC files while Packing

Packpanda can optionally create BAM and PYC files and ship them 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.

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.

In fact, this is related to the --bam and --pyc options mentioned earlier. In fact, packpanda always generates bam and pyc files. However, if you do not specify the --bam and --pyc options, then these files will be generated, verified, and then discarded. The effect of the --bam and --pyc options is to cause these files to be shipped to the end-user.

Preloading the Model Cache

If your distribution includes EGG files, and if you choose not to remove those using --rmext egg, then panda will convert them to BAM files at install time. This is a somewhat time consuming process, it makes the install take longer. If you want to avoid this, do not distribute EGG files --- instead, distribute BAM files, as explained above.

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

On Windows, 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: (not available on Linux)

Moving Beyond Packpanda

Packpanda has a lot of limitations. However, packpanda is actually a front end to more powerful systems. On Linux, it uses the system tools dpkg-deb and rpmbuild. On Windows, it uses 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 those systems 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 those base tools 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.