2.4.5.4 Using Crystal Space

Crystal Space programs can be run directly from the command-line or from the Finder. If you plan to launch programs by double-clicking on them in the Finder, then you must tell them where to find the resources which they require to run. This is accomplished by storing the path to the root of the Crystal Space directory in the MacOS/X defaults database under the name `CrystalSpaceRoot'. It is most useful to configure this setting in the global defaults domain. Depending upon your needs, you can set this to point at either the installed Crystal Space SDK or to the development directory where you built the project; either location works.

For example, if you have installed Crystal Space at the default location, then you can tell programs where to find their resources by invoking the following configuration command from the command-line:

defaults write NSGlobalDomain CrystalSpaceRoot "/usr/local"

If necessary, it is possible to configure `CrystalSpaceRoot' for a particular application. If you do so, this setting will override the global setting. For example:

defaults write walktest CrystalSpaceRoot "$HOME/CS"

It is also possible to instruct Crystal Space applications to ignore the value of `CrystalSpaceRoot' by assigning the `CrystalSpaceRootIgnore' option a value of `Yes'. This is most useful when you would like to have a particular application ignore the value of `CrystalSpaceRoot' set in the global domain. For example:

defaults write walktest CrystalSpaceRootIgnore "Yes"

Before attempting to run any of the Crystal Space sample applications, ensure that the files `standard.zip' and `stdtex.zip' reside in `CS/data' or in the `data' directory where Crystal Space is installed. These files contain resources and textures which are used by several of the example programs and map files.

You need to have one or more map files in order to run WalkTest. These are the files which contain the maps and rooms which you can explore with WalkTest. The most commonly used example map file is `flarge'.

You may need adjust the ambient lighting which the engine applies when it lights the maps. This may be necessary if you find that the scenes appears too dark. You can do this by setting ambient lighting values via the following configuration commands from the command-line. The default value for these settings is 20. If that is too dark for you, try using a higher value. For example:

defaults write CrystalSpace.Global Engine.Lighting.Ambient.Red 50
defaults write CrystalSpace.Global Engine.Lighting.Ambient.Green 50
defaults write CrystalSpace.Global Engine.Lighting.Ambient.Blue 50

If you want ambient lighting to apply to only a single application, or if you want to override the global setting with an application-specific setting, replace `CrystalSpace.Global' in the above commands with `CrystalSpace.Application' where `Application' is the name of the application (for example, `CrystalSpace.Walktest').

Important: The first time you explore a map after changing the ambient white value, you should run WalkTest with the `--relight' option. This causes Crystal Space to recalculate the lighting information in the map in order to take advantage of the new ambient light value. Note, however, that relighting a map may be time consuming, particularly for certain sizable maps, so be patient.

As a general rule, you may find it useful to specify the `--relight' option with newly downloaded maps, or at any other time that the lighting in a map seems somehow to be incorrect.

To specify options when running programs, you must invoke the programs from the command-line, however the need to specify command-line options is rare, so this should not prove much of an inconvenience.

To run WalkTest with a particular map (for instance, `flarge') for the very first time, for example, type:

./walktest.app/Contents/MacOS/walktest --relight flarge

Subsequent uses of the map file do not require `--relight', in which case you can type:

./walktest.app/Contents/MacOS/walktest flarge

Once invoked, you will be able to explore the map file (`flarge') by using the navigation controls (see section Movement Commands). To explore a different map, substitute its name in place of `flarge'.

If you would like to explore a map other than `flarge' without having to type it on the command-line, you can add the following setting to the MacOS/X defaults database. This will allow you to explore different maps even when launching WalkTest from the Finder. For example, to explore a map named `castle', set the following default value:

defaults write CrystalSpace.Walktest Walktest.Settings.WorldFile castle

Other interesting applications, such as csDemo, also come with Crystal Space.

By default, Crystal Space renders the 3D scenes with the OpenGL renderer. Some versions of the MacOS/X operating system ship with OpenGL drivers which do not not perform particularly well with the Crystal Space OpenGL renderer, and this problem could result in poor frame rates. Consequently, you may want to configure Crystal Space to instead use the software renderer. There are two ways to enable the software renderer. First, you may instruct a program to use software renderer from the command-line:

./walktest.app/Contents/MacOS/walktest --video=software flarge

Second, you can enable the software renderer on a permanent basis for all applications by setting the following default. Once you have applied this setting, you no longer need to specify `--video=software' on the command-line.

defaults write CrystalSpace.Global System.Plugins.iGraphics3D \
  crystalspace.graphics3d.software

Crystal Space renders 3D scenes in a window by default, however you can instruct the applications to use full-screen mode with the `--fs' command-line option. For example:

./walktest.app/Contents/MacOS/walktest --fs flarge

Alternately, if you prefer to launch programs from the Finder, you can install the following default setting to enable full-screen mode for all Crystal Space applications:

defaults write CrystalSpace.Global Video.FullScreen yes

It is also possible to enable full-screen mode selectively only for certain applications. For example, to enable full-screen mode only for CsDemo by default, you could apply this default setting:

defaults write CrystalSpace.csdemo Video.FullScreen yes

On the MacOS/X, Crystal Space will pause execution when the window is de-activated, and resume execution when the window is re-activated. Paused state is indicated by the text "[Paused]" in the title of the window. If you wish to disable this behavior, and allow programs to run even when the window is not active, apply this setting to your defaults database:

defaults write CrystalSpace.Global System.RunWhenNotFocused yes

You can also use the command-line option `--alwaysruns'.

This document was generated using texi2html 1.76.