@c -*-texinfo-*-
@node HOWTO Create Thing, HOWTO Create Genmesh, Writing MeshObjects, MeshObject
@subsection Creating a Thing Mesh
@cindex @code{iThingFactoryState}
@cindex @code{iThingState}
@cindex thing mesh

This section describes how to create a thing mesh.

@subsubheading What are Things?

A @samp{thing} mesh object (@pxref{MeshObject Thing}) is an object made
out of polygons. Every polygon can have another material and the polygons
can have three or more vertices. A thing uses lightmapping
for lighting (roughly this means that every polygon gets another texture
which contains light and shadow information for that polygon).

Things are useful for static geometry objects or objects that don't animate.
You can use it for walls, floor, staircases, and even doors that open. As
long as the object itself doesn't have to animate (but just moves) a thing
is perfectly fine. For very high detail objects it is probably better to
use the @samp{genmesh} mesh object (@pxref{MeshObject Genmesh} instead. Also
if you want to use internal animation (like an actor or a creature in your
game) you should use the @samp{sprite3d} mesh object (@pxref{MeshObject Spr3D}).

Things can share geometry if they are made from the same factory. Note that
information like lightmaps is not shared because a lightmap is position
dependent (i.e. the amount of light a polygon receives depends on where the
object instance actually is).

Note that you can hardtransform things (hardmove in maps). If you do this
on a mesh object instance then the factory will be cloned if it is used
by multiple mesh objects. That's because hardtransform essentially modifies
the original geometry and the geometry of a thing is always in the factory.
So beware of this because it may mean a lot of extra memory usage if you
hardtransform every instance created from a factory.

Note that individual polygons can have names. This can be useful for debugging
and also for attaching specific game features to some polygons (like indicating
if some polygon is a light switch button or something) but be aware that these
names add some memory overhead.

@subsubheading Creating a Thing in a Map

Here is an example of how to create a cube thing in a map file. Note that
in this example we avoid the use of a factory. We load a mesh object directly.
A factory will be created invisibly to support the thing geometry:

@example
<meshobj name="cube">
  <plugin>crystalspace.mesh.loader.thing</plugin>
  <params>
    <v x="-0.5" y="-0.5" z="-0.5" />
    <v x="-0.5" y="-0.5" z="0.5" />
    <v x="-0.5" y="0.5" z="-0.5" />
    <v x="-0.5" y="0.5" z="0.5" />
    <v x="0.5" y="-0.5" z="-0.5" />
    <v x="0.5" y="-0.5" z="0.5" />
    <v x="0.5" y="0.5" z="-0.5" />
    <v x="0.5" y="0.5" z="0.5" />

    <material>upMaterial</material>
    <p name="up">
      <v>3</v> <v>7</v> <v>6</v> <v>2</v>
    </p>
    <material>otherMaterial</material>
    <p name="north">
      <v>1</v> <v>5</v> <v>7</v> <v>3</v>
    </p>
    <p name="east">
      <v>5</v> <v>4</v> <v>6</v> <v>7</v>
    </p>
    <p name="south">
      <v>4</v> <v>0</v> <v>2</v> <v>6</v>
    </p>
    <p name="west">
      <v>0</v> <v>1</v> <v>3</v> <v>2</v>
    </p>
    <p name="down">
      <v>0</v> <v>4</v> <v>5</v> <v>1</v>
    </p>
  </params>
  <move>
    <v x="1" y="0" z="3" />
  </move>
</meshobj>
@end example

There is a lot more you can do in a thing. For example you can specify
exactly how you want to map the texture on the polygons.
In this particular example we create a cube that
has another material for the upper polygon.

@subsubheading Creating a Thing from Code

Here we create the same thing from code. We use a convenience function in
the engine to create a thing (@code{CreateThingMesh}).

@example
iMaterialWrapper* upMaterial = @dots{}
iMaterialWrapper* otherMaterial = @dots{}
csRef<iMeshWrapper> walls = engine->CreateThingMesh (room, "cube"));
csRef<iThingState> ws =
  scfQueryInterface<iThingState> (walls->GetMeshObject ());
iMeshObject* walls_object = walls->GetMeshObject ();
iMeshObjectFactory* walls_factory = walls->GetFactory();
csRef<iThingFactoryState> walls_state = 
    scfQueryInterface<iThingFactoryState> (walls_factory);
walls_state->AddQuad (
  csVector3 (-.5, .5, -.5),
  csVector3 (.5, .5, -.5),
  csVector3 (.5, .5, .5),
  csVector3 (-.5, .5, .5));
walls_state->SetPolygonMaterial (CS_POLYRANGE_LAST, upMaterial);
walls_state->SetPolygonTextureMapping (CS_POLYRANGE_LAST, 3);
@dots{}
@end example

This is only an extract of the example but you can easily see how to create
additional polygons here.

@subsubheading Include Files

The include files useful for this section are:

@example
#include <imesh/thing.h>
@end example
