[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ] [ Search: ]

5.3 Simple Map Example

This HOWTO shows you a very simple map you can make by using a world file and explains a few of the concepts in it.

Here is the map:

 
<world>
  <textures>
    <texture name="andrew_wood">
      <file>/lib/stdtex/andrew_wood.jpg</file>
    </texture>
  </textures>
  <materials>
    <material name="wood">
      <texture>andrew_wood</texture>
    </material>
  </materials>
  <plugins>
    <plugin name="thing">crystalspace.mesh.loader.thing</plugin>
  </plugins>

  <sector name="room">
    <meshobj name="walls">
      <plugin>thing</plugin>
      <zfill />
      <params>
        <v x="-10" y="-1" z="10"/> <v x="10" y="-1" z="10"/>
        <v x="-10" y="-1" z="-10"/> <v x="10" y="-1" z="-10"/>
        <v x="-10" y="4" z="10"/> <v x="10" y="4" z="10"/>
        <v x="-10" y="4" z="-10"/> <v x="10" y="4" z="-10"/>
        <material>wood</material>
        <texlen>4</texlen>
        <p name="up">
          <v>6</v> <v>7</v> <v>5</v> <v>4</v>
        </p>
        <p name="down">
          <v>3</v> <v>2</v> <v>0</v> <v>1</v>
        </p>
        <p name="back">
          <v>7</v> <v>6</v> <v>2</v> <v>3</v>
        </p>
        <p name="front">
          <v>4</v> <v>5</v> <v>1</v> <v>0</v>
        </p>
        <p name="left">
          <v>6</v> <v>4</v> <v>0</v> <v>2</v>
        </p>
        <p name="right">
          <v>5</v> <v>7</v> <v>3</v> <v>1</v>
        </p>
      </params>
    </meshobj>
    <light>
      <center x="0" y="3" z="0"/>
      <radius>40</radius>
      <color red="1" green="1" blue="1"/>
    </light>
  </sector>
</world>

The structure of the map file is nested. At the highest level there is the ‘world’ keyword which represents the entire world. Inside the world the two first sections describe the textures and materials. A texture is basically a direct representation of an image on disk. In this case we define a texture called ‘andrew_wood’ which corresponds to the texture file ‘/lib/stdtex/andrew_wood.jpg’. Keep in mind that the filename is a VFS file! See section Virtual File System (VFS). A texture is not directly usable on geometrical objects. Before we can use it we need to make a material as well. The reason for this is that with materials we can define many other additional effects (like multi-texture materials and so on). In this example we define a material called ‘wood’ that uses the ‘andrew_wood’ texture.

The engine itself does not render any geometry. Mesh objects are responsible for that. See section Mesh Object Plug-In System. These are separate plugins. This duality is also present in the map loader. The map loader itself does not know how to parse geometrical objects. It will delegate the loading of mesh objects to mesh object loaders (again separate plugins). In the ‘PLUGINS’ section we indicate what plugins we are going to use in this map file. In this case we are only going to use the ‘crystalspace.mesh.loader.thing’ loader which loads generic polygon based objects. We call this plugin ‘thing’.

In this simple example we only have one sector in the world called ‘room’. If you need multiple sectors you can use multiple ‘sector’ statements. In the room sector we have one mesh object (‘meshobj’) and one light (‘light’).

When defining mesh objects there are several things to keep in mind. Aside from the geometry which is handled by the mesh object plugin, the engine also keeps track of some stuff. Important to know is that everything inside the ‘params’ block is given to the plugin loader. So the engine doesn't know about that. Everything that is outside ‘params’ is handled by the engine itself. The first thing that has to be said in the ‘meshobj’ block is which plugin is going to be used for loading this object. In this case we use the ‘thing’ plugin. Then we tell the engine that we would like to use ‘ZFILL’ mode for rendering this object. This means that the Z-buffer will be filled but not read. This is usually used for exterior walls because Crystal Space does not clear the Z-buffer at the start of every frame (by default). See section Render Priorities and Objects in Sectors.

The rest of the mesh object is defined inside the ‘params’ block and this is what will be parsed by the thing loader plugin. Keep in mind that different types of plugins will have different syntax. So the discussion following here is only relevant for ‘thing’ mesh objects.

First we define all vertices that we are going to use in this mesh object. In this case we use eight vertices for the eight corners of the room that we are creating. Then we say that all following polygons will use the ‘wood’ material. The ‘texlen’ command is a bit more complicated to explain. Basically if we had a polygon that was 4x4 units big, then a texture using ‘texlen(4)’ would be tiled exactly one time on that polygon. So the ‘texlen’ command directly specifies the texture density or the amount of times a texture is tiled. For more information about this see see section Texture Mapping.

Finally we define the six polygons that form the walls of our room. Polygons don't have to have names but in this case we use names to make it clearer what they are. For every polygon we indicate what vertices (from 0 to 7) it uses. Keep in mind that a polygon is only visible from one side. The vertices should be oriented in clock-wise direction from the viewpoint where you want the polygon to be visible. So in this case we make a room which means that all polygons have to be visible from the inside. If we were to make a box then you can do this by reversing the order of all vertices of all polygons.

Much more is possible in map files. This howto only shows the very basic stuff.


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

This document was generated using texi2html 1.76.