4.16.2.1 Initalization Section

This section describes the initialization section.

Texture Specification Section

Here is an example texture specification section:

<textures>
  <texture name="wood">
    <file>/mygamedata/wood.png</file>
  </texture>
  <texture name="transp">
    <file>/mygamedata/stripes.png</file>
    <transparent red="1" green="0" blue="0"/>
  </texture>
  <proctex name="plasma">
    <type>plasma</type>
  </proctex>
</textures>

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:

<materials>
  <material name="table_material">
    <texture>wood</texture>
  </material>
  <material name="fence_material">
    <texture>transp</texture>
  </material>
  <material name="plasma_wood">
    <texture>wood</texture>
    <shader type="standard">std_lighting_detail_alpha</shader>
    <shadervar name="tex detail" type="texture">plasma</shadervar>
    <shadervar name="detail texture scale"
               type="vector2">10,10</shadervar>
    <shadervar name="detail texture color"
               type="vector4">1,1,1,0.25</shadervar>
  </material>
</materials>

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:

<shaders>
  <shader><file>/shader/reflect.xml</file></shader>
</shaders>

Most of the times you simply refer to shaders from a file.

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:

<sounds>
  <sound name="ear-joy.mp3" mode3d="relative" />
  <sound name="waterfall.mp3"
    file="waterfall_179384.mp3"
    mode3d="absolute" />
</sounds>

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:

<sounds>
  <sound name="mysong.wav" mode3d="disable">
    <file>mysong.wav</file>
  </sound>
</sounds>

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:

<variables>
  <variable name="avatar_age" value="21.0" />
  <variable name="sky_color">
    <color red="0.0" green="0.0" blue="1.0" alpha="1.0" />
  </variable>
  <variable name="that_way">
    <v x="-0.5" y="3.5" z="0.5" />
  </variable>
</variables>

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 thing, spr3d, and spr3dfact plugins:

<plugins>
    <plugin name="thing">
        crystalspace.mesh.loader.thing
    </plugin>
    <plugin name="spr3dFact">
        crystalspace.mesh.loader.factory.sprite.3d
    </plugin>
    <plugin name="spr3d">
        crystalspace.mesh.loader.sprite.3d
    </plugin>
</plugins>

Settings Section

In the settings section there are a few configuration options that you can specify. Here is a complete settings example:

<settings>
  <clearzbuf />
  <clearscreen />
  <lightmapcellsize>16</lightmapcellsize>
  <maxlightmapsize horizontal="256" vertical="256" />
  <ambient red=".1" green=".1" blue=".1" />
  <fastmesh>300</fastmesh>
</settings>

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’.

The lightmap cellsize defines how many texels (pixels on a texture) there are in every lumel (lightmap value). For example, if the lightmap cellsize is 16 (default) then for every 16x16 texels there will be one lumel.

The maximum lightmap size is usually 256x256. You can change this value here but this usually doesn't make much sense.

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.

With ‘fastmesh’ you can control at which point Crystal Space will use ‘CS_THING_FASTMESH’ for a thing. This is a faster routine (in principle) but at this moment it only seems to pay off for objects with a high number of polygons. The default is 500.

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:

<start>
    <sector>room</sector>
    <position x="0" y="0" z="0" />
</start>
<start name="alternate">
    <sector>other_room</sector>
    <position x="0" y="0" z="0" />
    <up x="0" y="-1" z="0" />
    <forward x="0" y="0" z="-1" />
    <farplane a="0" b="0" c="1" d="100" />
</start>

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:

<key name="spawn_monster" type="ghost" location="mainhall"
  pos="10,1,12" />
<key name="spawn_monster" type="goblin" location="corridor"
  pos="15,3,10" />

This document was generated using texi2html 1.76.