@c -*-texinfo-*-
@node Simple Map Example, Blender, Map Creation, Working with Engine Content
@section Simple Map Example
@cindex @code{iImage}

This @sc{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:

@example
<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>
@end example

The structure of the map file is nested. At the highest level there
is the @samp{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 @samp{andrew_wood} which corresponds
to the texture file @file{/lib/stdtex/andrew_wood.jpg}. Keep in mind that
the filename is a @sc{vfs} file! @xref{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 @samp{wood} that uses
the @samp{andrew_wood} texture.

The engine itself does not render any geometry. Mesh objects are responsible
for that. @xref{MeshObject}. 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 @samp{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 @samp{crystalspace.mesh.loader.thing}
loader which loads generic polygon based objects. We call this plugin
@samp{thing}.

In this simple example we only have one sector in the world called @samp{room}.
If you need multiple sectors you can use multiple @samp{sector} statements.
In the room sector we have one mesh object (@samp{meshobj}) and one light
(@samp{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 @samp{params} block is given to the plugin loader. So the engine doesn't
know about that. Everything that is outside @samp{params} is handled by
the engine itself. The first thing that has to be said in the @samp{meshobj}
block is which plugin is going to be used for loading this object. In this
case we use the @samp{thing} plugin. Then we tell the engine that we would
like to use @samp{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). @xref{HOWTO Render Priorities}.

The rest of the mesh object is defined inside the @samp{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 @samp{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
@samp{wood} material. The @samp{texlen} command is a bit more complicated
to explain. Basically if we had a polygon that was 4x4 units big, then
a texture using @samp{texlen(4)} would be tiled exactly one time on that
polygon. So the @samp{texlen} command directly specifies the texture density
or the amount of times a texture is tiled. For more information about this
see @pxref{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.
