5.6 md32spr Tutorial

Written by Manjunath Sripadarao, [email protected]. Last updated 17 December 2002.

This tutorial provides a brief introduction to md32spr application. You can use this application to convert Quake III MD3 models to Crystal Space model format. The md32spr source files can be found in `CS/apps/import/md32spr/'. Typing `make md32spr' should build the application (after configuring Crystal Space for your particular architecture).

Required Resources

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

Converting the Model

• Unzip the contents of `mdl-conni.zip' into a temporary directory.
• Among the contents, find the file named `conni.pk3' and unzip it using a tool which can unpack ZIP-style archives. (PK3 files are just ZIP archives in disguise.)
• Next go to the directory `models/players/conni/'.
• Zip the contents of this file using a tool for creating ZIP-style archives; call this file `conni.zip'.
• Copy `conni.zip' to the `CS/data/' directory.
• Now run the following command:

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

• This should give you an output file named `conni_out.zip' in the `CS/data/' directory.

Loading a Model in Walktest

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

./walktest -recalc data/conni_out.zip

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

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

Description of Archive Contents

The output sprite archive `conni_out.zip' contains the following files.

• head
• upper
• lower
• head.tag
• upper.tag
• lower.tag
• conni.tga

The `head', `lower' and `upper' files contain the meshobjects. The file `conni.tga' is the texture file. The files `head.tag', `lower.tag' and `upper.tag' contain the MD3 tags.

MD3 Tags

The 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 MD3 tag structure represented as C++ code:

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

In the Crystal Space map format (which is XML), these tags are placed in a separate file with a `.tag' extension. The format of these tags is shown below.

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

For example:

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

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.

Miscellaneous md32spr Information

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.

• 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.
• Some 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 MD3 file. Subsequently, you may end up with a 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.
• The loading of Crystal Space format XML models is somewhat slow presently. You can speed it up by converting your models to binary format using VIEWMESH. I have not personally tried it. But if anyone wants any help let me know.
• Type ./md32spr without any arguments to get a brief command line help.

Sample "World" file

Here is the sample `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.

<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.thing</plugin>
      <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>
      <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>

This document was generated using texi2html 1.76.