In this example we define three textures. The first one is called
‘wood’ and will be loaded from the VFS file
‘/mygamedata/wood.png’. See section Virtual File System (VFS).

The second texture, ‘transp’, is loaded from
‘/mygamedata/stripes.png’. The red color will be made fully
transparent. If you want to use an alpha channel then this is supported
too. In that case simply load a PNG image that has an alpha channel (or
any other type of image that supports an alpha channel).

The third texture is a procedural texture. There are four types of
procedural textures predefined in Crystal Space: ‘fire’, ‘water’,
‘dots’, and ‘plasma’.

Subcommands allowed for a texture specification are:

‘key’‘Key/value node’. Specifies a generic key/value.

‘for2d’‘Boolean’. Texture is for 2D usage.

‘for3d’‘Boolean’. Texture is for 3D usage (default).

‘transparent’‘Color’. Texture uses keycolor with the given color.

‘file’‘String’. VFS filename for the texture.

‘mipmap’‘Boolean’. Texture uses mipmaps (default on). For 2D textures it is
usually better to disable this. Also skybox textures should probably disable
this.

‘npots’‘Boolean’. Texture doesn't have to be power of two and it will
not be scaled to power of two dimensions. (default off). Note that not all
hardware supports this, and sometimes this only works if mipmaps are
disabled as well as clamping enabled.

‘clamp’‘Boolean’. If set the texture will not be tiled and color lookups
outside the 0..1 range will be clamped to the edge of the texture. Default off.

‘filter’‘Boolean’. If disabled then no texture filtering will occur. This usually
looks worse. Default is on.

‘keepimage’‘Boolean’. If this is set then the loaded image will be kept
and attached to the texture for later usage. With this flag off (which is
default) the image will be freed after the texture is given to the
3D renderer (to conserve memory).

‘type’‘String’. Name of the texture plugin. Some examples of texture
plugins are ‘crystalspace.texture.loader.water’,
‘crystalspace.texture.loader.plasma’,
‘crystalspace.texture.loader.checkerboard’,
‘crystalspace.texture.loader.cubemap’, ...

‘params’‘Node’. Parameters for the optional texture plugin.

‘size’‘Attributes 'width' and 'height'’. Desired size of the texture. This
is mainly useful in case you use one of the texture plugins. If you use a
normal file then the width and height is fetched from the image.

‘alwaysanimate’‘Boolean’. If this is an animated texture then this flag will
make sure the texture keeps animating even if out of view. This is less
performant but in some cases it is more correct. Default off.

‘class’‘String’. This is used to specify the class of the texture. One
common example is ‘normalmap’ which is used by many shaders.

‘alpha’‘String’. One of ‘none’, ‘binary’, ‘smooth’, or ‘auto’.
‘binary’ is often used to force binary alpha for an alpha mapped texture.
In short, by using this flag the texture can be used on regular objects using
‘zuse’ and ‘object’ render priority. This greatly helps performance
and correct visual appearance of objects. For a more detailed explanation
see section Alpha and Keycolor in Textures.

Material Specification Section

Materials are very important in Crystal Space. Almost all objects will
use materials to define the surface characteristics of their geometry.
A material itself is usually made from one or more textures.

Here is an example material section. It uses the textures defined
in the previous section:

When defining materials you usually use a name that indicates the use of that
material. That way you can easily replace how the material looks like (by
swapping textures) without having to change the material name itself.

In the example above we first define a ‘table_material’ which uses only
the ‘wood’ texture. The second material is ‘fence_material’ which
uses the semi-transparent ‘transp’ texture.

The last material is interesting. The base of the material is the
‘wood’ texture. On top of that there is an additional texture layer
that uses the ‘plasma’ texture. The layer is scaled 10 times in both
u and v direction and it is added to the original texture
(i.e. the colors are added). This “special effect” is achieved by attaching
the ‘std_lighting_detail’ shader to this material. Different shaders
allow different effects - the additive blending of a second texture in this
case.

Subcommands allowed for a material specification are:

‘key’‘Key/value node’. Specifies a generic key/value.

‘texture’‘String’. Name of the texture.

‘color’‘Color’. A color instead of a texture. If you use this then ‘texture’
should not be used.

‘shader’‘String’. A shader to use for this material. The value of this should
be the name of the shader to use. In addition you also need to specify
the ‘type’ (as an attribute) of this shader. This will be used in combination
with the renderloop to control when this material will be used in the rendering
steps.

‘shadervar’‘Value’. This defines a variable for the shader attached to this material.
The meaning of a variable as well as the required type depends on the specific
shader A shader variable has two attributes: ‘name’ and ‘type’.
‘name’ is the name as used in the shader. The type can be anything like
‘texture’, ‘vector2’, ‘vector3’, ‘vector4’, ‘integer’,
‘float’, ‘expr’, ‘expression’, or ‘array’.

Shader Section

With shaders you can describe more advanced texture and material
effects. Here is an example:

Sounds Section

The ‘sounds’ Section of the map file format allows you to encode
information about the sound effects, background music, or pre-recorded
dialogues that you want to include in the map. Here is an example of
a 'sounds' section of a map file:

As you can see, you can include multiple ‘sound’ nodes within a
‘sounds’ node, and there are three attributes that determine the
behavior of each ‘sound’ node. Here is an overview of what each of
the attributes do:

‘name’‘String’. The ‘name’ attribute is the internal Crystal
Space VFS identifier for the sound object. This is usually identical to
the filename for the object.

‘file’‘String’. The ‘file’ attribute is the external filename for the
sound object, which may be different than the sound object's Crystal Space
name. Most of the time, though, the ‘file’ attribute will be left
blank, and its default value will be the value of the ‘name’ attribute.

‘mode3d’‘Enum’. The ‘mode3d’ attribute can be one of: ‘absolute’,
‘disable’, or ‘relative’. If ‘mode3d’ is not one of these
three values or empty, then the ‘crystalspace.maploader.parse.sound’
error is reported.

As mentioned above, it is possible to omit, the ‘file’ attribute and
let it default to ‘name’, because ‘name’ is required. However,
if you want the Crystal Space name to be different than the filename,
use the ‘file’ attribute as well. An alternative to using ‘file’
attribute (for example: ‘file="mysound.wav"’ to indicate the filename
of a sound object, you may instead use a ‘file’ element (for example
‘<file>mysong.wav</file>’) within a ‘sound’ node to load a
sound from a filename. Here is an example of how it would look:

As mentioned earlier, The ‘mode3d’ enumeration is one of:
‘absolute’, ‘disable’, or ‘relative’. The following is a
breakdown of what each of these options implies:

‘disable’
When ‘mode3d’ is ‘disable’ then no signal processing is done
to the sound object. This mode allows stereo audio to be stored in a
sound object. Both other modes only allow one channel.

‘relative’
When ‘mode3d’ is ‘relative’ then some level of signal processing
is done to ensure that the sound being played will have different volumes
depending on the ‘position’ parameter of the sound object. Note that
only one-channel sound objects are allowed.

‘absolute’
When ‘mode3d’ is ‘absolute’ then the highest level of signal
processing is performed. Like ‘relative’ this mode only works with
one-channel sound objects. Unlike ‘relative’, this mode translates
absolute coordinates into relative listener coordinates, allowing the
calculation of the sound output by finding the difference between the
user and the sound object, so the volume of the sound object will seem
to vary as you move about.

Variable Section

The variables section of a map file format allows you to define
variables, and make shortcuts for common strings, colors, and vectors.
Here is an example of a variables section of a map file:

As you can see, the variables section can contain multiple
variable elements, each of them defining a variable definition.
Within each variable definition, depending on the type, you can specify
different attributes. Here is an overview of the attributes and
elements that can be found within a variable element:

‘name’‘String’ attribute,
The name of the variable.

‘value’‘String’ attribute
A string value associated with the variable name.

‘color’ element
A color value associated with the variable name. A ‘color’ element
can have ‘red’, ‘green’, ‘blue’, and optionally
‘alpha’ attributes, where each attribute can be assigned a value
between 0 and 1. If the ‘alpha’ attribute is omitted, then it is
assumed to have a value of 1.

‘v’ element
A vector value associated with the variable name. A ‘vector’ element
can have ‘x’, ‘y’, and optionally ‘z’ attributes, where
each attribute is any floating point number. If the ‘z’ attribute
is omitted, then it is assumed to have a value of 0.

Plugin Section

The plugin section is purely for convenience later. Normally when creating
mesh objects you have to specify the SCF class name of the loader
which will parse the XML data for that mesh object. This is a long
name. The plugin section allows you to define shorter names for those
plugins. Here is an example where names are defined for the genmesh,
spr3d, and spr3dfact plugins:

By default Crystal Space does not clear the z-buffer not the screen every
frame. For the z-buffer it depends on objects to fill the z-buffer. In a
typical Crystal Space world every sector would have an outer hull (either
a skybox or else the walls of the room) which would use ‘zfill’ mode
so that the z-buffer is updated but not read. Objects in the room can then
use ‘zuse’. If you don't want this (i.e. you want to use ‘zuse’
for all objects) then you can use ‘clearzbuf’. Similar for
‘clearscreen’.

In addition to the lighting information given by all lights in the system,
every object will also get ambient lighting. Ambient lighting is global to
the engine (at least static ambient lighting). You can set the ambient
for a level in the settings block. Default ambient is 0.078 for all color
components.

Start Location Section

A map file can contain zero or more start locations for the camera. How
these start locations are interpreted is up to the application. Typically
there is one start location that has no name and which is considered the
default. But you can have multiple start locations and refer to them by
name in your application. Here is an example:

If there is no start location then by convention many applications assume
that the default start is in sector called ‘room’ at location
‘0,0,0’.

The first example above is easy. It just defines the same starting location
as specifying nothing would have done.

The second example is more complicated. It defines a start location called
‘alternate’. The up-vector is specified as ‘0,-1,0’ which is just
the reverse of the default ‘0,1,0’. This means that the camera will
be upside down. The forward vector is ‘0,0,-1’ which means that
the camera will be looking to the negative z axis. By default the camera
looks in the positive z direction.

The last ‘farplane’ option is interesting. It indicates that all
geometry beyond ‘z=100’ will be clipped away. You can use this if
you want to speed up rendering and you know that objects further away than
the specified distance are not interesting or you use fog that would have
made them invisible anyway. Note that fog alone doesn't do that. By default
there is no farplane. If you use the farplane option it is usually recommended
to let the engine clear the z-buffer every frame (see the ‘settings’
section above) because you can no longer depend on geometry to do it for you
if it is culled away.

Library Specification Section

It is possible to define libraries that contain objects like mesh factories,
textures, materials, and so on and then include those libraries in your
map files. Creating a library file is very easy. It is basically the same
as creating a map file but instead of <world> you would use
<library>. To use a library you can simply put the following in
your map file:

<library>/mygamedata/library</library>

Keys

Crystal Space has a system with which you can attach user data to almost
all Crystal Space objects. This user data has a name and several values (string
based) and in code you can query for those name/value pairs. Crystal Space
itself doesn't use this. It only stores the information.

When you specify name/value pairs in the world section itself you are
essentially adding information to the engine class. Here is an example: