Model Definitions

Overview

Models are defined in XML files that contain not only the model info, but also the state to frame mappings that are linked to the Decorate state frames.

Models.xml

On startup, Vavoom will look for a models.xml file in the models directory. This file has to contain the following header and footer:

<?xml version="1.0" encoding="UTF-8" ?>
<vavoom_models_list>
</vavoom_models_list>

Between the header and the footer the file contains links to your definition XML files:

<include file="path/to/defintionfile.xml" />

You can organize your definition XML files using as many folders as you want, just make sure each file is referenced with the relative path from where models.xml resides.

Definition XML files

Technically, you can put all your model definitions into a single XML file, but if you have more than just a few models, it’s more manageable to use a number of separate files.

Each model definition file has to contain the following header and footer:

<?xml version="1.0" encoding="UTF-8" ?>
<vavoom_model_definition>
</vavoom_model_definition>

Between the header and the footer, you can add two kinds of main blocks: models and classes.

Models

A model block has the following structure:

	<model name="bluemana">
		<md2 file="models/mana/blue.md2">
			<frame index="0" scale_x="1.5" scale_y="1.5" />
		</md2>
	</model>

Mandatory attributes for model entries

  • name: this must be unique inside this XML file

MD2

Inside a model block, you must add at least one MD2 block (you can also specify more than one MD2 model, creating in-game models that go beyond the format’s limitations on vertices and triangles).

An MD2 block has the following structure:

                <md2 file="models/mana/blue.md2">
			<frame index="0" scale_x="1.5" scale_y="1.5" />
                </md2>

Mandatory attributes for MD2 entries

  • file: the file name including the full path

Optional attributes for MD2 entries

  • version: according to the MD2 specs, it must be 8, but there is no need to define this attribute at all
  • position_file: this feature seems to provide the ability to specify a model inside a file that contains several models (?)
  • skin_anim_speed: used to specify skin animations
  • offset_x / offset_y / offset_z: floating point number to position the model in the game world differently than the source object (can be negative numbers as well)
  • scale / scale_x / scale_y / scale_z: floating point number to scale the model along one or several axis (use values smaller than 1.0 to shrink the object)
  • fullbright: if set to true, the specified (part of the) model will have the highest light level (if used with some but not all md2 file definitions within a model definition, it can e.g. create a two-part candle where only the flame is bright)
  • noshadow: the model (part) won’t cast a shadow, even if model shadows are turned on in the rendering options

Frames

Each MD2 block inside a model block needs to contain at least one frame entry.

Mandatory attributes for frame entries

  • index: the unique ID of a frame within the model. This is an integer starting at 0

Optional attributes for frame entries

  • offset_x / offset_y / offset_z: floating point number to position the model in the game world differently than the source object (can be negative numbers as well)
  • scale / scale_x / scale_y / scale_z: floating point number to scale the model along one or several axis (use values smaller than 1.0 to shrink the object)
  • alpha_start / alpha_end: allows the definition of alpha translucency for both the beginning and end of the frame (if both values are defined and they are different, the translucency of the model will change during the frame’s display time)
  • skin_index: the index number of a skin; needed only if not the default skin (which has the index 0)

Classes

A class block has the following structure:

	<class name="KRPGMana1">
		<state index="0"  model="bluemana" frame_index="0" angle_start="0.0" angle_end="360.0" />
	</class>

Mandatory attributes for class entries

  • name: the Decorate class using this model

States

Each class block needs to contain at least one state entry.

Mandatory attributes for state entries

  • index: this corresponds to a Decorate frame (see the Decorate article for more information, as this works completely differently than sprite frames)
  • model: the name attribute of a model block within the XML file
  • frame_index: the index attribute of a frame within an MD2 block in the model block specified previously

Optional attributes for state entries

  • alpha_start / alpha_end: allows the definition of alpha translucency for both the beginning and end of the frame (if both values are defined and they are different, the translucency of the model will change during the frame’s display time)
  • inter: floating point values ranging from 0.0 to 1.0, allowing for more than one frame within a single state index entry
  • angle_start / angle_end: rotates the object around the Z axis (if both values are the same, the model is simply “pointed” into a certain direction but not animated within the specific state)

You can assign the same frame to different states of either the same class block or different class blocks. You can also assign frames of different models to different states of a single class block.