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:

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:

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.

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: