Crystal Space 2.0.0: 5.4.2.1 Initalization Section

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 5.4.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:

#### 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:

#### 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:

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:

#### 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:

#### 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:

    <plugins>
        <plugin name="genmesh">
            crystalspace.mesh.loader.genmesh
        </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 />
      <ambient red=".1" green=".1" blue=".1" />
    </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’`.

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:

    <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" />

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated using texi2html 1.76.