@c -*-texinfo-*-
@node md32spr Tutorial, mdl2spr, COLLADA, Working with Engine Content
@section @code{md32spr} Tutorial
@cindex Tutorial, Sprite (@code{md32spr})
@cindex @code{md32spr} Tutorial

@noindent
@emph{Written by Manjunath Sripadarao, @email{msripada@@evl.uic.edu}.
Last updated 17 December 2002.}

This tutorial provides a brief introduction to @code{md32spr} application.  You
can use this application to convert Quake III @sc{md3} models to Crystal Space
model format.  The @code{md32spr} source files can be found in
@file{CS/apps/import/md32spr/}.  Typing @i{@samp{make md32spr}} should build
the application (after configuring Crystal Space for your particular
architecture).

@subheading Required Resources
@cindex Required Resources, @code{md32spr} Tutorial

For this tutorial we will be using the ``Conni'' model from
@uref{http://www.polycount.com/}.  The name of the file is
@file{mdl-conni.zip}.  Download the file to a local directory.

@subheading Converting the Model
@cindex Converting the Model, @code{md32spr} Tutorial

@itemize @bullet
@item
Unzip the contents of @file{mdl-conni.zip} into a temporary directory.

@item
Among the contents, find the file named @file{conni.pk3} and @dfn{unzip} it
using a tool which can unpack @sc{zip}-style archives.  (@sc{pk3} files are
just @sc{zip} archives in disguise.)

@item
Next go to the directory @file{models/players/conni/}.

@item
Zip the contents of this file using a tool for creating @sc{zip}-style
archives; call this file @file{conni.zip}.

@item
Copy @file{conni.zip} to the @file{CS/data/} directory.

@item
Now run the following command:

@example
./md32spr data/conni.zip -o=data/conni_out.zip -scale=4096
@end example

@item
This should give you an output file named @file{conni_out.zip} in the
@file{CS/data/} directory.
@end itemize

@subheading Loading a Model in Walktest
@cindex Loading a Model in Walktest, @code{md32spr} Tutorial

To load the model into Walktest, copy the sample world file given below to a new file named world.
Add this @file{world} file to the archive @file{conni_out.zip} using a @sc{zip}-capable archiver, and then
issue the following command:

@example
./walktest -recalc data/conni_out.zip
@end example

This will allow you to view the model in Walktest.  The @file{world} file
defines a sample map and the @dfn{mesh objects} that make up the model.  If you
are curious, you can use a text editor to look at the @file{world} for more
information.  The sample @file{world} file is also reproduced below for
convenience (@pxref{Conni Output,Sample ``World'' file}).

@strong{Note}: The model here is loaded into walktest for testing purposes.
Normally in your application there won't be a @file{world} file for each of
your models.  You have to load and animate your models using code.

@subheading Description of Archive Contents
@cindex Description of Archive Contents, @code{md32spr} Tutorial

The output sprite archive @file{conni_out.zip} contains the following files.

@itemize @bullet
@item
@code{head}
@item
@code{upper}
@item
@code{lower}
@item
@code{head.tag}
@item
@code{upper.tag}
@item
@code{lower.tag}
@item
@code{conni.tga}
@end itemize

The @file{head}, @file{lower} and @file{upper} files contain the
@dfn{meshobjects}.  The file @file{conni.tga} is the texture file.  The files
@file{head.tag}, @file{lower.tag} and @file{upper.tag} contain the @sc{md3}
tags.

@subheading @sc{md3} Tags

The @sc{md3} tags are bits of information which specify the spatial location
and orientation of the mesh objects for each frame.  Here is an example of an
@sc{md3} tag structure represented as C++ code:

@example
char Name[64];  // Name of the 'tag'.
Vec3 Position; // Relative position of tag.
Vec3x3 Rotation;// Direction tag faces relative to rest of model.
@end example

In the Crystal Space map format (which is @sc{xml}), these tags are placed in a
separate file with a @file{.tag} extension.  The format of these tags is shown
below.

@example
<key name="md3tag"
  tag="<tag_name> <frame_num> <tag_num>
       <xpos ypos zpos> <3x3 rotation matrix>" />
@end example

For example:

@example
<key name="md3tag" tag="tag_torso 0 1  1 0 0 0 1 0 0 0 1  0 0 0" />
@end example

If your model does not have any animation or your model is made up of only one
mesh object, then you may not have these tags.

@subheading Miscellaneous @code{md32spr} Information
@cindex Miscellaneous @code{md32spr} Information, @code{md32spr} Tutorial

This section will tell you if there are any special issues to worry about.
Currently these are the known issues.  If I come across anything else I will
amend this section.

@itemize @bullet
@item
Currently, in the mesh object files at the end, there are example mesh objects
definition.  These are not required to load the model, but they are left there
as an example.  You should comment it out manually to reduce memory usage.

@item
Some @sc{md3} model converters do not write any frame number information if a
model is not animated.  This causes garbage numbers to be read from the
@sc{md3} file.  Subsequently, you may end up with a large number (possibly in
the thousands or hundred-thousands) duplicate frames which actually do nothing.
Until now I have not been able to find a solution to this problem.  Any
comments, suggestions or corrections are welcome.

@item
The loading of Crystal Space format @sc{xml} models is somewhat slow presently.
You can speed it up by converting your models to binary format using
@sc{viewmesh}.  I have not personally tried it.  But if anyone wants any help
let me know.

@item
Type @code{./md32spr} without any arguments to get a brief command line help.
@end itemize

@anchor{Conni Output}
@subheading Sample ``World'' file

Here is the sample @file{world} file for the ``Conni'' model. You need to copy this
to a new file and add that file to conni_out.zip. For the model to work in Walktest.

@example
<world>
  <library>lower</library>
  <library>upper</library>
  <library>head</library>
  <textures>
    <texture name="abstract_a032.gif">
      <file>/lib/stdtex/abstract_a032.jpg</file>
    </texture>
    <texture name="andrew_wood.gif">
      <file>/lib/stdtex/andrew_wood.jpg</file>
    </texture>
  </textures>
  <materials>
    <material name="wood">
      <texture>andrew_wood.gif</texture>
    </material>
  </materials>
  <sector name="room">
    <meshobj name="walls">
      <plugin>crystalspace.mesh.loader.genmesh</plugin>
      <params>
        @dots{}
      </params>
      <zfill />
    </meshobj>
    <light>
      <center x="0" y="0" z="9" />
      <radius>40</radius>
      <color red="1" green="1" blue="1" />
    </light>
    <light>
      <center x="0" y="0" z="-9" />
      <radius>20</radius>
      <color red="1" green="1" blue="1" />
    </light>
    <light>
      <center x="-9" y="0" z="0" />
      <radius>20</radius>
      <color red="1" green="1" blue="1" />
    </light>
    <light>
      <center x="9" y="0" z="0" />
      <radius>20</radius>
      <color red="1" green="1" blue="1" />
    </light>
    <meshobj name="headh_head">
      <plugin>crystalspace.mesh.loader.sprite.3d</plugin>
      <params>
	<factory>h_head</factory>
	<action>default</action>
      </params>
      <move>
	<matrix>
	  <rotx>-1.5708</rotx>
	</matrix>
	<v x="-1" y="0.45" z="3" />
      </move>
    </meshobj>
    <meshobj name="upperu_torso">
      <plugin>crystalspace.mesh.loader.sprite.3d</plugin>
      <params>
	<factory>u_torso</factory>
	<action>TORSO_STAND</action>
      </params>
      <move>
	<matrix>
	  <rotx>-1.5708</rotx>
	</matrix>
	<v x="-1" y="0.26" z="3" />
      </move>
    </meshobj>
    <meshobj name="lowerl_legs">
      <plugin>crystalspace.mesh.loader.sprite.3d</plugin>
      <params>
	<factory>l_legs</factory>
	<action>LEGS_IDLE</action>
      </params>
      <move>
	<matrix>
	  <rotx>-1.5708</rotx>
	</matrix>
	<v x="-1" y="0" z="3" />
      </move>
    </meshobj>
  </sector>
</world>
@end example
