How to add new media to Sear

Sear has a layered approach to assigning a model to a particular entity for rendering. Sear uses a ModelRecord to specify information about a particular model and a ObjectRecord to map an entity name to one or more ModelRecords. A model record may also point to further configuration files specific to the type of model. The following section will go into more details.

It should be noted here that all models are static apart from Cal3D models. Sear currently ignores any animations in 3DS and MD3 models.

ObjectRecords

ObjectRecords typically live in a file called "object_records.cfg" that comes as part of the media package. This file has a list of records specifying the entity type, whether to draw this entity, whether to draw any contained entites, and a list of models associated with this entity.

The following chunk is an example object record for a settler entity.

  [settler]
  draw_self = "true"
  draw_members = "false"
  low_quality = "settler_cal3d"
  medium_quality = "settler_cal3d"
  high_quality = "settler_cal3d"

As can bee seen from this example, the entity type is contained within square brackets. This signifies the start of one record and the end of any previous record. Following this is a boolean value, draw_self. This tells Sear to render models for this entity. The draw_members boolean tells Sear whether to render and entities contained. For character entities such as the settler this should be false (these are the inventory items and will be hidden about the person). Other entity types such as buildings and boxes should show their contents and this flag should be set to true.

The final items here are the [low|medium|high]_quality options. These specifies the names of ModelRecords. Multiple models can be speficied by having multiple [low|medium|high]_quality lines. These allow you to use a low quality model for objects that are far away and higher quality ones for closer models. The main idea is e.g. billboards for far away and animated models for close up.

ModelRecords

ModelRecords typically live in a file called "model_records.cfg" that comes as part of the media package. It is similar in format to that of the object records.

The section shows an example modelrecord for the settler cal3d model.

  [settler_cal3d]
  model_loader = "cal3d"
  state = "character"
  select_state = "select"
  outline = "true"
  rotation_style = "normal"
  data_file_id = "settler_cal3d_id"
  scale_height = "true"

This example shows the name of the model record in square brackets and matches with the name specified in the objectrecord low_quality option. This record has a few important fields that need to be specified. These are the model_loader, state and select_state field. The model_loader field specified the type of model and how to load it. E.g. "cal3d" means that this is a cal3d model, "3ds" means it is a 3D studio max file. See below for more specific details on the different model loader types.

Field Name	Description
model_loader	The type of model this is
state	The is the state record name for normal rendering. See states.cfg
select_state	The is the state record name for rendering in selection mode. See states.cfg
outline	True to use stencil techniques to render the outline of the object. False to colour the whole object instead.
rotation_style	Affects how the model is rotated. "normal" takes the orientation from the server. "none" applies no rotation. "position" rotates the object in the z axis based on position. "billboard" and "halo" rotate the object to face the camera.
scale_height	Scale entity by the height of the bounding bo if applicable.
scale_by_bbox	Scale the model by the entity bounding box if applicable
scale	Defines a scaling factor to apply to the model.
model_by_type	Only load one instance of this model. Used for non-animated objects.
data_file_id	Used by some model loaders as entry name in models.cfg. The entry points to a model loader specific config file.
data_file_path	Used in CVS sear to hold the filename directly instead of in the external file.
offset_x	Applies a translation to the model in thex direction
offset_y	Applies a translation to the model in thex direction
offset_z	Applies a translation to the model in thex direction
shader_texture	Used by the Area shader to specify the texture to use.

WireFrame Loader

model_loader = "wireframe"

This model loader draws a wireframe box representing the bounding box of the entity. Entities with no bounding box will be drawn as a 1m by 1m by 1m box.

BoundBox Loader

model_loader = "boundbox"

This is identical to the wireframe loader, except it will attempt to render the box with a texture of the same name as the object record it is associated with.

NPlane Loader

model_loader = "nplane"

This loader allows rendering of billboards. The number of planes to render is specified by adding num_planes = "1" to the model record. Change 1 to the number of planes required. The planes are equally spaced around a circle. The texture name used the name of the object record it is associated with.

Cal3d Loader

model_loader = "cal3d"

This loader creates objects using the Cal3D library. It uses data_file_id as the name of an entry in the cal3d section of the models.cfg file. This entry value is the filename of a .cal file.

See the The .cal file format. for more details.

3ds Loader

model_loader = "3ds"

This loader creates objects using the lib3ds library. It uses data_file_id as the name of an entry in the 3ds section of the models.cfg file. The entry value can either be a .3ds file directly, or a .vconf file. If data_file_path is specified, then it points directly to one of these two files.

See the 3DS File Format for more details.

MD3 Loader

model_loader = "md3"

This loader creates objects using the libmodelfile library. It uses data_file_id as the name of an entry in the md3 section of the models.cfg file. The entry value can either be a a .md3 file directly, or a .vconf file. If data_file_path is specified, then it points directly to one of these two files.

See the The MD3 File Format for more details.

Area Loader

model_loader = "area"

This loader is used to add area data to the terrain engine.

What's Next?

Once you have added a new model and tested that is works, let me (simon AT simongoodall.co.uk know and it can be added to the main media for Sear.