Model skins

From SIMboxWiki
Jump to navigation Jump to search

The model skins feature provides the ability to create several paint schemes for a single 3d model. In the context of SIMbox graphic engine this is achieved by layering different images on top of a model.

The purpose of this feature is to make it easier to generate a large number of similar objects that look different. A good example of this will be generating a crowd of people or coloring different aircraft in large formation.

This feature is implemented in SIMbox version 5.6 and above. This feature only works in SimiGon Graphic Engine Version 5 (SGEV5).

System Mechanism

We will give an example to explain how this feature works.


The content developer wishes to create a large crowd of people that look randomly different. Instead of generating a model for each person in the crowd and than a simulation object for it, the artist generates a single model of a person, and uses the model skin system to allow the developer to generate the different looks.

The artist includes a script file with the model that contains the definitions for the model skin system. Using this file the artist defines layers for the model. Each layer defines a different component to be controlled. Examples for such layers can be: shirt, pants, skin complexion, hair color and beard type. Each layer has several different variants. The shirt layer can contain variants such as: green shirt, red shirt and tan shirt. The pants layer may contain the variants such as: black trousers, tan shorts and blue jeans. Each variant is assigned to a different texture which contains an image of that variant. The green shirt variant will therefor link to a texture containing the image of a green shirt.

The model is sent back to the content developer. The content developer uses the graphic engine's API to select a different variant each layer to be displayed. The graphic engine takes these selections and combines them into a single texture. It then projects that image on top of the model.

Layer Order

It is important to note that when the graphic engine combines the different layer textures it layers them one on top of the other. It is therefor important to keep in mind the order in which the different layers should be combined. In our example, if the artist uses bearded layer textures containing semi-transparent areas, then the skin complexion layer should come before the bearded layer. This is to allow the skin complexion color to show through (underneath) the semi-transparent bearded.

Multi-texture Objects

The skin model mechanism works by replacing the existing texture of a model. Some models contain more than one texture. In this case each variant can be assigned with multiple textures to replace a different texture in the model.

How to Use

To use the SIMbox graphic engine model skins feature there are two points you need to address. The first is to prepare the 3d model and script file. The second is to request the graphic engine to use the model skins feature in code.

Content Preparations

In order for the model skin system to work the artist needs to supply a 3d model and a script file. The script file will define the different layers and variants of the skin for a given model

Script File and Format

The script defining the skin for a given 3d model is placed as part of the "model" script file. The script file should have the extension '.model' and should be placed in the same directory as the original model.

The content of the model should have the following format:

 model [Model filename]
       layer [Layer name] 
           variant [Variant name] {variant texture} {target texture} 
           variant [Variant name] {variant texture} {target texture}
       layer [Layer name 2] 

  ... [Other model properties]


  • [Model filename] - (required) The name of the mesh file which this script is to be used on. for example "person.mesh"
  • [Layer name] - (required) The name of the layer. In the above supplied example this may be: shirt, pants, "skin complexion", "hair color", "beard type", etc...
  • [Variant name] - (required) The name of the variant. In the above supplied example this may be: "green shirt", "red shirt", "tan shirt", "black trousers", "tan shorts", "blue jeans", etc...
  • [Variant texture] - (optional) The name of the texture representing the given variant. If no texture name is supplied than no texture will be used to represent the given variant. In the above supplied example this may be: green_shirt.png, red_shirt.png, etc...
  • [target texture] - (optional) in model containing more than one texture this parameter can be used to tell which original model texture the variant texture needs to replace. If this parameter is left out the variant texture will replace all original textures in the model.

Note: Names which contain space need to be surrounded with a quotation symbol (").

To prepare a model for the alternate skins feature, place the alternate textures and the skins file in the same folder as the model.

Script Order

Note:The order in which the different layers and variants appear in the script is important.

The order in which the layers and placed in the script is the same as the order in which they are combined into an image in the graphic engine. This means that an image from a given layer variant will be placed below a second layer variant image if that layer was defined before the second layer in the script.

The order of the variants is also important. The first variant in each layer will be the default variant selected by the graphic engine.

 Texture Size and Format

All textures which replace the same target texture in the model must share the same size. The textures are than layered one on top of the other in the same position.

While a specific format is not required for the skin texture. The skin texture format must contain an alpha channel. It is suggested that the artist is to use a .png format instead of the more widely used dds. This is because the textures tend to contain large transparent areas. These type of images are well compressed in the .png format with little or no loss of color definition. It is not important to use dds texture as the texture themselves are never uploaded to the graphic card.

Using Model Skins in Code

There are 4 functions which allow direct control over the skinning feature.

  • TriD::EnumObjectSkinLayers - The EnumObjectSkinLayers function will enumerate the different skin layers available in a given object. Note that the output of this function is dependent on the .model script file you have prepared (from the previous section).
  • TriD::EnumObjectSkinLayerVariants - The EnumObjectSkinLayerVariants function will enumerate the different skin layer variant available in a given object for a specific layer. Note that the output of this function is dependent on the .model script file you have prepared (from the previous section).
  • TriD::SetObjectSkinLayerVariant - The TriD::SetObjectSkinLayerVariant function will set the selected layer variant for a given layer in a given object to be used.
  • TriD::GetObjectSkinLayerVariant - The TriD::GetObjectSkinLayerVariant function will return the selected layer variant for a given layer in a given object.

Instancing and Model Skins

The object instancing system of the graphic engine also utilizes the model skin system. Selectiion of skins for instanced object is done though functions specific to the object instancing system.



To optimize speed each time a new layer variant combination is selected an image of that combination is created and stored in a cache. This cache is positioned in a directory under the 3d model directory to which the image belongs. The cache is deleted only if one of the files in the model directory is changed.