Panda3D Manual: Building a Self-Extracting EXE using packpanda
<<prev | top | next>> |
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;
packpanda --bam # Ship BAM files packpanda --pyc # Ship PYC files
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:
packpanda --rmdir dir # Strip all directories with given name packpanda --rmext ext # Strip all files with given extension
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:
packpanda --name "Evil Space Monkeys of The Planet Zort"
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:
packpanda --version X.Y.Z # Assign a version number
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:
packpanda --fast # Quick but not so great compression
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.
<<prev | top | next>> |