Errors and Crashes

Error at startup referring to barewords and use strict

This can happen to WinZip users on Win32. If you extract the PIGGE tarball using WinZip instead of cygwin tar, make sure to turn off WinZip's "smart" conversion of CR/LF. It is decidely not smart, and will cause PIGGE to die on startup. Or just use cygwin tar, of course.

Error at startup complaining about bad config file line

This can be caused by two different common mistakes. First, you may have forgotten to put quotes around a config override containing spaces. Second, you may have tried to load a different scene file by directly specifying it on the command line like this:

./pigge-run demos/demo.cfg simple.yaml

Instead, you need to specify it as a config override like this:

./pigge-run demos/demo.cfg world.scene=simple.yaml

Error at startup complaining that config file could not be opened

PIGGE does not yet search for config files in any sort of search path (though that is a planned feature). In the mean time, you must specify the relative or absolute path to the config file -- demos/demo.cfg rather than just demo.cfg.

Other errors or crashes on startup

First, check that you have all of the prerequisites specified in the installation guide. If these all check out, make sure that OpenGL is working using the glxinfo and glxgears commands. If both programs function normally, make sure SDL_Perl is working properly by trying another SDL_Perl application such as Frozen Bubble. If this also works, we're down to operating system specific issues:

FreeBSD
You may need to use the LD_PRELOAD hack to fix an SDL threading issue. Issue the following before attempting to run your PIGGE application (thanks to Todd Ross for this suggestion):
setenv LD_PRELOAD /usr/lib/libc_r.so

Rendering Issues

There's a black window and nothing happening

You probably started pigge-run without specifying a configuration file. Without a configuration file, PIGGE defaults to an empty scene (nothing to view), a black background, and no statistics or other displays to indicate that something is going on. The standard way to start pigge-run requires that a configuration file be specified on the command line, like so:

./pigge-run demos/demo.cfg

You can also use more than one config file, and override individual configuration settings by specifying them on the command line. For example, you could load the demo config as above, but choose a simple scene file and optimization for software GL drivers as follows:

./pigge-run demos/demo.cfg world.scene=simple.yaml softgl.cfg

Note that config file names and individual settings can appear in any order on the command line. Individual settings must appear as a single argument on the command line; if you need spaces, surround the setting in quotes like so:

./pigge-run demos/demo.cfg 'app.title = A Nice Long Title'

Everything in the standard demo appears very dark

Your SDL_perl has probably not been patched to fix the SvNOK bug. Win32 users should upgrade to an SDL_Perl later than 1.20.3 (the last version with this bug). Users of other operating systems can either apply the patches in the above bug report and recompile, or pester the relevant package maintainer to do so. In the mean time you can turn off lighting (though that's pretty ugly) using:

./pigge-run demos/demo.cfg render.lighting=0

Additional settings on the command line don't take effect

PIGGE processes configuration files and command lines in strict left to right order, and the last setting for a config item wins. For example, since the demo.cfg config file sets the world.scene config item, this will not do what the user may expect:

./pigge-run world.scene=simple.yaml demos/demo.cfg

demo.cfg will override the previous setting of world.scene, and it will appear to have no effect. The solution is to reverse the order of arguments:

./pigge-run demos/demo.cfg world.scene=simple.yaml

This loads the simpler demo scene while still keeping the other settings from demo.cfg, as expected.

Performance

It's really slow, almost a slide show

You may be using software OpenGL when you expected hardware OpenGL instead. Check the output of glxinfo. If your 'OpenGL renderer string' is 'Mesa GLX Indirect' or something similar, you are using software rendering and complex scenes will render very slowly. Unfortunately, the resolution of this problem is very dependent on exactly which OS and distribution you are using. Debian users with nVidia hardware should take a look at the packages listed by apt-cache search nvidia; these are mostly in the non-free/x11 section.

If you are stuck with software OpenGL, try turning on software OpenGL optimizations using the softgl.cfg config file:

./pigge-run softgl.cfg demos/demo.cfg

These optimizations are highly dependent on the content of the scene. Simple scenes, or scenes containing only simple objects, will gain very little benefit. On the other hand, complex scenes, especially those containing many complex objects and particle effects, will see quite a bit of improvement in frame rate (enough that it may even be noticed on a system with a hardware renderer).

It's slower than expected, and I'm rendering over the network

First, make sure that the network itself is not your bottleneck. This may be caused by a real network limitation (such as attempting to render from one machine to another across a WAN), or it may be because of network encryption slowing things down. If you are using X (and GLX) over a secure local network, you might want to set your DISPLAY variable so that it sends directly to the X display (typically at :0.0), rather than through the encryption tunnel (typically at :10.0). You may need to use the xhost command to enable this on the display machine. NOTE: This is not secure. You have been warned. Don't do this if you are not willing to take the risks yourself. Read the relevant manpages and know what you are getting into!

Also, make sure you turn on remote rendering optimizations using the remotegl.cfg config file, as follows:

./pigge-run remotegl.cfg demos/demo.cfg

The frame rate drops noticeably when rendering particle effects

You may need to reduce the complexity of the particle effects. The relevant config settings (and their default values) are:

render.show.particles            = 1
render.texture.particles         = 1
render.particles.size            = 1.0
render.detail.geometry.particles = 7

render.detail.geometry.bias      = 0
render.detail.textures.bias      = 0

The first setting allows particle effect rendering to be turned off entirely (though effects still use CPU because the particles are still updated internally). The next setting determines whether particles are textured, which may be a performance issue when software rendering, but is unlikely to be an issue for most hardware OpenGL renderers. The third setting determines the size of each particle in world units. The fourth setting determines the base geometry detail level for particle effects. This translates to the number of particles in each effect, and is on a log scale. The default value sets 2 ^ 7 = 128 particles per effect.

The last two settings are global detail bias settings; they affect not just particles, but every available detail setting (including some that are defined in scene files, rather than config files). Small negative values will greatly reduce particle effect complexity, but remember that many other things in the world will suddenly lose detail as well. This may in fact be what you want for some cases -- see softgl.cfg and q3.cfg, which among other things set negative detail biases to allow PIGGE to work better with software renderers.

You will probably need to try a few different combinations of settings before finding one that gives acceptable performance without giving up too much visually. The first setting to fiddle with is render.detail.geometry.particles, as that directly affects rendering requirements, memory usage, and CPU utilization (CPU time is needed for physics and other particle update calculations).