[Sear Home]

The Cal3D (.cal) file format

.cal files are used to specify Cal3D models for Sear. They are read in by Varconf and so have the same syntax. This document describes how to create a .cal file to load in a new Cal3D model. Please see Media Team for more information about adding new models to Sear to actually use it.

The basic .cal file has one section, entitles [model] and requires at least one entry called "skeleton".

  [model]
  skeleton = "skeleton.csf"
  scale = "1.0"
  path = "${SEAR_MEDIA}/settler/"
  rotate = "180.0"

In this example there is also an entry called "scale" which applies a scaling factor to the model. It also has a path entry, which if it exists, is prefixed to every filename in the .cal file. The rotate field specifies in degrees a rotation about the z axis. This is used for models that face the wrong direction.

Most character models should be scaled by the height of their server defined bounding box. This allows for characters to grow. One example is pigs growing as they get fatter. In order to help with this, a flag scale_isotropic_z = "true" can be set in place of the normal scale factor to scale the object first to a unit height (based upon the height of the default model in it's initial pose) before rescaling again to the bounding box height.

Cal3D models are, in addition to a skeleton, composed of meshes, materials and animations. The only restriction in the order they appear in the .cal file is that materials need to be defined in the correct order. Cal3d meshes use an index to specify materials instead of names. Materials are assigned an index in the order they are loaded. Failure to do so will result in the wrong materials being assigned to the meshes.

Animations

Animations are specified under the [model] section in the form animation_name = "animation.caf" where name is the name of an action or mode set by the server in an entity. Currently mode represents a repeating action (such as walking) by the entity and action represents a single action (such as a wave). Each model should have an animation for default, idle, standing, walking and running, swimming, attack, collapse (used to indicate loosing the battle) and touch. (for character entities at least). This list is subject to change and may increase over time. The default animation will be used if there is no animation avaialble.

In addtion to specifying a single animation per mode or action, Sear allows multiple animations to be combined together. Instead of specifying animation_running under the model section, it is possible to create an animation running section. This section then lists all the animations to combine (as a key) along with a weighting (as the value). For example, the following snippet combines an animation called run and an animation called flutter to make the real running animation.

  [animation_running]
  animation_run = 1.0
  animation_flutter = 1.0

Meshes

Two types of meshes are defined in Sear. These are permanent meshes e.g. body parts, and user selectable meshes, e.g. clothing. Meshes are defined as mesh_name = "filename" for permanent and mesh_name_n = "filename" for selectable. Name is an arbitrary name of the mesh and is used by the /set_app command in Sear to identify the mesh. n in the selectable meshes is a number starting from 1 used to distinguish between meshes for the same item (e.g. shorts and trousers). Only one of these meshes can be used at once.

Materials

Materials are the more complex item to configure. A material is defined as material_name_part = "filename" where name is the name of the material (a name of default needs to be defined) and part describes the group the material belongs to (e.g. pants)

Materials need to be defined in the order expected by the cal3d files as they are accessed by index. Materials of the same part can be grouped together however.

Material settings can be overridden in the .cal files. Most commonly these can be to alter the texture map name, or adjust alpha values. These values can be overridden by creating a new section with the same name as the material identifier. E.g. a line material_default_pants = "blahblah.crf" would have a section [material_default_pants]. The following table describes the available parameters.

NameDescription
texture_map_nSpecifies the texture name for the nth texture map (starting at 0)
ambient_redA value between 0 and 255 for the ambient red component.
ambient_greenA value between 0 and 255 for the ambient green component.
ambient_blueA value between 0 and 255 for the ambient blue component.
ambient_alphaA value between 0 and 255 for the ambient alpha component.
diffuse_redA value between 0 and 255 for the diffuse red component.
diffuse_greenA value between 0 and 255 for the diffuse green component.
diffuse_blueA value between 0 and 255 for the diffuse blue component.
diffuse_alphaA value between 0 and 255 for the diffuse alpha component.
specular_redA value between 0 and 255 for the specular red component.
specular_greenA value between 0 and 255 for the specular green component.
specular_blueA value between 0 and 255 for the specular blue component.
speculae_alphaA value between 0 and 255 for the specular alpha component.
shininessA value between 0 and 128 for the shininess component.

Wielding items

In CVS, Sear has some new options to help with correctly wielding entities. The first, is a new section called bone_mapping which links the wield slot specified by the server to the name of a bone in the model. The second item is a rotation to apply to the bone. This rotation is aimed to make sure all bones are rotated into the same coord space. E.g. in the has of a hand, some models may specify the Z axis parallel to the fingers, others may specify it as perpendicualr. This is currently a mapping between the wield slot name and a semi-colon demilited list of four numbers representing the w, y, and z components of a quaternion.

  [bone_mapping]
  right_hand_wield = "Bip01 R. Hand"
  left_hand_wield = "Bip01 L. Hand"

  [bone_rotations]
  right_hand_wield = "1.0;0.0;0.0;1.0"