SIMbox Mesh Exporter User Guide

From SIMboxWiki
Jump to navigation Jump to search

SIMbox Mesh Exporter User Guide

What’s New

Changes in version 1.2.2:

  • Support for 3ds Max versions 2011 to 2014.
  • Ability to export models with multiple texture maps (composite maps) and with different blending modes.
  • Ability to export environment maps
  • Easier default handling of transparent materials
  • Ability to define bone animations from the track bar using time tags and export animations directly from the SIMbox menu.


To install the Mesh Exporter plugin:

  1. Make sure 3ds Max is not running.
  2. On the course CD, navigate to the folder Utilities\Mesh Exporter.
  3. Run SIMboxMeshExporter_3dsmax.exe
  4. Select the 3ds Max versions you wish to use with the Mesh Exporter.
  5. Open 3ds Max once the Mesh Exporter installation is finished. The SIMbox menu is added to the application’s main menu.

To un-install the Mesh Exporter:

  1. Open the operating system’s remove programs feature (the name is different for each version of Windows) and scroll down to “SIMbox 3ds Max Mesh Exporter”.
  2. Click on “Change/Remove”. You will be prompted to either reinstall or uninstall. Select Uninstall.
  3. Once the un-installer has finished, open 3ds Max. Notice the SIMbox menu is still there. Follow the next steps if you wish to remove it; otherwise, you are done.
  4. From the “Customize” menu select “Customize User Interface…”. Once the dialog opens, switch to the “Menus” tab.
  5. The right-hand side of the dialog shows the main application menu as a tree. Right-click the “SIMbox” entry and select “Delete Menu Item” from the context menu.
  6. Click the “Save” button and save over the startup menu settings file (MaxStartUI.mnu).

To re-install the Mesh Exporter:

If the Mesh Exporter is re-installed and the SIMbox menu does not appear, follow this procedure:

  1. From the Maxscript menu, select “Run Script…”
  2. Navigate to the SIMboxMeshExporter folder inside 3ds Max’s program folder
  3. Select and run


The mesh exporter is used to export 3ds Max scenes to the Ogre3D mesh format used by SimiGon’s simulation engine.

The SIMbox mesh file format comprises three file types. The main file type has the extension mesh. During export, two other files are also saved – one has the extensions .skeleton and the other .material. All three are necessary to display the file properly.

The exporter supports several types of objects and materials, and can export several types of animations – object-based animation (with multiple objects), skeleton-based animation (on a single object). It can also export vertex-based animations such as one that you create with a morph modifier.

Preparing Your Model for Export

Object settings

Object limitations

You can use any object type that can be converted to an editable mesh or poly inside 3ds Max, as well as dummies and groups. Other objects – lights, cameras, etc. - will be ignored during export.

Duplicate object names are not allowed. Duplicate objects will be renamed during export.

Notice: The maximum number of objects in a single scene is 256. If more than 256 exist in the scene, the exporter will fail to function.

Skinned Vs. multiple objects

In general, objects exported to mesh can be divided into two types:

  • A model consisting of multiple rigid parts, usually some kind of vehicle, tool or building with separate objects for wheels, control surfaces etc.
  • A scene consisting of an organic / flexible object such as a character or a balloon.

In the first case, of a multi-part rigid object, object creation and editing is straightforward.

The second case has slightly different rules. First of all, only a single object is treated as the main object – the one that is eventually exported. This object must have a skin modifier in its modifier stack. The skin modifier must not contain more than 256 bones.

Mixing rigid and soft parts

Sometimes, it is also necessary to mix the two types of objects – a model may have a flexible rubber hose or cloth part, but also some hard metal or plastic parts.

If you want to mix soft and rigid parts, you must begin by modeling everything as separate rigid objects. Once you are done, you need to unify your model into a single skinned mesh.

To convert your object from a multi-object scene to a single skinned object, open the SIMbox menu and select Unify Mesh. The process might take several seconds.

The scene now contains a single mesh with a skin modifier, as well as controller objects in the shape of bounding boxes with a green wireframe. These controllers retain all the properties of the original objects, including animations. When they are moved the corresponding part of the skinned mesh move as well.

You can now assign bone weights to vertices in the object using the Skin modifier tools to create flexible segments. You can also use other modifiers if you want to create pose animations.

The result of the Unify Mesh operation

Material Settings

The Mesh Exporter only recognizes standard materials or multi/sub materials that contain standard materials. Other material types, such as Blend or Raytrace, will result in a failure to export. Similarly, there are limits on map types. If a map type other than Bitmap, Composite or Normal Bump exists in the scene, the scene will be exported but the non-standard map will be ignored.

Any number of materials, multi/sub materials or combinations thereof can exist in the scene. Note that the exporter combines them into a single multi/sub material in the first stage of the export.

Objects with no material at all are assigned a default material during export.

Notice: Spaces are not allowed in material names. Any spaces in material names will be changed to underscores during export.

The following instructions were written using the “compact” mode of 3ds Max’s material Editor but the same techniques apply for the Slate Editor as well.

Setting up basic material parameters

Most of the basic material parameters are supported when exported to mesh. They are marked in the image below.

  • Glossiness, opacity, wire and 2-sided are supported normally.
  • For materials lacking textures, set up the Ambient and Diffuse colors as you normally would.
  • For materials with textures, in order for the textures to appear in the simulation with their original colors, you should set the Ambient and Diffuse values to white (RGB: 255,255,255). Otherwise, the textures will appear tinted or darkened.
  • Instead of adjusting the Specular Level spinner, you can adjust the Specular color’s brightness.
  • To add self-illumination, check the box next to it to change the spinner into a color control. Instead of adding an opacity map, use an alpha channel in your texture.

UI basicmaterial.png  Color values for textured materials


The mesh exporter only supports the export of Bitmap maps. Procedural maps such as Noise or Marble are ignored during export. Bitmaps can be of almost any type – Jpg, PNG, BMP, TGA – but the preferred type is DDS.

The following map types are supported:

  • Diffuse color
  • Specular level (only in KnowBook / SIMbox versions 5.6.2 and above)
  • Reflection
  • Bump

There are certain limitations and procedures to each of these types, as described below.

Diffuse textures

There are two types of maps that can be exported to mesh from the diffuse color slot: Bitmap and Composite. Once the bitmaps is loaded, most of the parameters in the coordinates rollout are exported: you can offset, scale and rotate the texture and change the tiling from a tiled texture to a decal texture by checking off the “tile” checkboxes. You can also set the UV channel.

If the texture has an alpha channel, it is interpreted as an opacity map. There is no need to add the texture to the opacity slot – this slot is ignored when exporting to mesh.

UI mapattributes.png

Using a Composite Map in the diffuse slot

Composite maps are a way to organize multiple textures into a layer stack, similar to the layer stack in Photoshop.

At this time, support for composite parameters is partial: only the texture and blending mode are supported.Also, alpha channels are ignored if a layer blend other than normal is used. Parameters inside the bitmap unit, such as UV channel, offset and tile, are still exported – so it is possible to use different sizes and UV channels for each texture.

Composite maps can be used to achieve effects such as:

  • Decal layers – small details over another low-resolution texture (use normal blend mode)
  • Detail layer – add extra small surface details such as cracks and grain to a larger texture (use overlay or hard light blend modes)
  • Ambient Occlusion Maps – add pre-rendered shadows to a model (use substract blend mode)
  • Light maps – add simulation-controlled light maps to a model.

UI composite.png  Compositemap.jpg

Opacity map

The mesh exporter does not use the opacity map slot. However, if the diffuse texture (or, if a composite map is used, the first layer in the composite stack) has an alpha channel, this will be used as an opacity map.

There are two types of opacity supported by the SimiGon graphic engine:

  • Alpha blending, which supports 256 levels of transparency, and is suitable for cases such as windows and semi-transparent surfaces, but does not work well when multiple overlapping transparent surfaces are to be used.
  • Alpha rejection, which has either completely transparent or completely opaque pixels. This technique works well when overlapping surfaces are needed, for example vegetation or fences.

An example of Alpha Blending  Alpharejection.jpeg

The default opacity mode is Alpha Blending. If you want to set the mode to Alpha Rejection, open the Bitmap Parameters rollout and uncheck the checkbox next to Premultiplied Alpha.

UI premultiplied.png

Normal maps

Normal maps emulate depressions and protrusions on a surface by changing the surface’s normal. They are similar to bump maps but instead of using grayscale levels to indicate height, they contain pre-calculated normals in all three directions – X, Y,Z - held in the R,G,B channels accordingly. Normal maps are generated either from a high-resolution model using texture baking process, or from a 2D bump map using a Photoshop filter.

To define a normal map, add a map of the type Normal Bump to the Bump map slot.

The Normal Bump map has two slots, Normal and Additional Map. In the Normal map slot, add a Bitmap map and then select the normal file (such as dds) as usual. Leave the Additional Map slot empty.

In the Method group, select either Tangent or Local XYZ, according to the type of normal map you have.

When this file is exported, the material file will contain the necessary parameters and the mesh file will contain some additional data necessary to render the model correctly.

Notice: Adding the normal map parameters manually to the material file will result in strange looking rendering artifacts. Only exporting with the described material setup produces a properly-rendered normal map.

UI normalmap.png  Normalmap.jpg

Reflection (environment) map

A reflection map is a special type of bitmap that is applied to the model using camera-dependent coordinates instead of coordinates fixed to the surface. As such, it can emulate the look of a reflected environment, although it is not an actual reflection of the model’s surroundings.

The ideal texture for use in this type of map is a spherical panorama image.

It is also possible to use dds cubemap textures.

The reflection map is the only map in which the opacity spinner in the map list affects the exported file. You can use it to make the material appear more or less reflective.

Spherical.jpg  Environemntmap.jpg

Environment Mask

Instead of having a uniform environment map you can set up a mask to only let the environment map affect certain areas of the texture.
The mask file is not set up as a grayscale bitmap as you normally would in 3ds max. Rather, the mask needs to be in an image’s alpha channel. The RGB channel can be left blank (i.e., white).
In the alpha channel, the lighter the value of the pixel, the stronger the environment map is going to be.
To set up an environment map with a mask:

  • Click the Reflection slot. The Material/Map Browser opens.
  • Select a Mask map. The Material Editor now shows two slots: Map and Mask.
  • Click the Map slot. In the Material/Map browser, select “bitmap” and then choose your environment map file.
  • Click the Go To Parent button to go up to the mask parameters rollout. Click the Mask slot. In the Material/Map browser, select “bitmap” and then choose your mask file.
  • In the bitmap’s Coordinates rollout, change the mapping type to Texture (it is initially set to Environment).
  • In the Bitmap Parameters rollout, set the Mono Channel Output to Alpha.

Environment mask settings.png

Envmask file.jpgEnvmask.jpg


The SimiGon Simulation engine can use two types of animations: bone animations, meaning animations of bones in a skinned mesh, or the position and rotation of objects, and pose animations – changes in the geometry, or morphing, of a single object. While most animations can be achieved by bone movement, some types of animations, such as facial animation, cloth movement, or the expansion or contraction of objects, requires pose animation.

Technically, bone animation records the movement of whole bones, while pose animation records the movement of individual vertices. When exported, the mesh file does not contain key-frames like the animation inside 3ds Max; the 3ds Max animation is sampled (with a user-specified sampling rate, but usually once per frame) and the result is recorded in the mesh file.

An example of node-based animation:

An example of pose Animation:

Several animations can be saved in a single file by animating them consecutively across several frame ranges. For example, a human character model can have a "standing idle" animation loop on frames 0-200, a walk loop on frames 210-45, and a jumping animation on frames 250-280.

Important: each animation sequence has to start with the scene in the same state as that of frame 0. Otherwise, unexpected animation artifacts might occur.

Sample rate

Since the mesh file’s animation is sampled from the 3ds Max scene at a constant rate, the file becomes larger the higher the sample rate. The sample rate is defined by the scene’s frame rate. Before you start animating, select an appropriate frame rate. If the animation is long and slow, it is preferable to use a lower frame rate – 15 or 10 frames per second – instead of the default 30fps. This will not cause choppy animation in the simulation since it will be interpolated anyway.
To select a different frame rate, open the Time Configuration dialog by right-clicking the animation playback controls at the bottom of the 3ds Max window, and then setting the Frame Rate to custom:

UI framerate.png  UI changerate.png

Bone Animations

The exporter can handle any type of node animation, including any type of external controller, script-based animation, rigging with IK solvers, parameter wiring etc., as long as the result of this animation is a movement or a rotation of an entire object or bone, and not a change in a modifier. In order to use your animations in the simulation, you must name them and define their start and end frames.

To define animations, use animation tags – descriptions that are attached to animation frames. These can be defined and edited by clicking the “Add Time Tag” label at the bottom of the 3ds Max window:

To define the start of a bone animation move the time slider to the start frame of the animation you wish to define. Click the Add Time Tag label and select Add Tag. The Add Time Tag dialog opens. In the Name field, type the animation name followed by the tag [sb] – along with the brackets (sb as in “start bone”).

UI tags.png  UI tag-add.png

To define the end of a bone animation, move the slider to the end frame of the animation. Create a Time Tag with the same animation name but use [eb] instead of [sb].

Do this for all the animations you wish to define in the file. The tags you defined will now appear in the Time Tag menu and should look like the image below.

UI tag-define.png  UI taglist.png

Pose Animations

Unlike bone animations, pose animation can only be created on a single object. Any type of modifier or 3ds Max animation method is legitimate; the Mesh Exporter sampler considers only the final output of the modifier stack.

To be able to export an object with pose animations, you must add a skin modifier to said object. If you do not add a skin modifier the pose animations will not be exported properly. Instead, all scene objects will be exported, including any control objects (such as morph targets) you use to define the pose animation, but only bone animations will actually work.

To define pose animations, use time tags again – [sp] for the start and [ep] for the end.

Mixing animations

It is possible to mix both types of animations in the same model, but not in the same animation sequence. For example, you might want to use morph targets to create facial animations on a skinned character; you can do this by adding the morph modifier as well as a skin modifier and using both types of animations; but you must take care to only animate the morph modifier in sequences defined as pose animations, and animate the bones that control the skin modifier in sequences defined as bone animations.

See Also: Testing Animations

Exporting Your Model

SIMbox Menu

In order to be able to export a model to mesh, the model must be a single object with a skin modifier and bones. But instead of doing this manually, the Exporter can be invoked through a script that converts a multi-object scene to a single skinned object during export.

If you followed the installation instructions in the beginning of the document, you now have a SIMbox menu item on the main menu. Click the menu. The SIMbox menu contains four items: Unify Mesh, Export Mesh As…, Export Mesh and Remove Spaces.

The Unify Mesh item unifies a scene into a single object without exporting. The resulting object’s name depends on the name of the 3ds Max scene and the state of the Remove Spaces item.

The Export Mesh As… item exports a file to mesh into a folder of your choice. You must choose a name with no spaces, otherwise an error message appears and the export is canceled.

The Export Mesh item exports a file with the same name and in the same folder as the current scene. If there are any spaces in the scene’s file name, the resulting name of the mesh file depends on the state of the Remove Spaces item.

When the Remove Spaces item is checked, the exporter trims everything after the first space in the name. This can be useful; since 3ds Max can save files sequentially (for example, Myfile 01, Myfile 02 etc.), this allows you to export the same mesh file name from different versions of the max file.

When the Remove Spaces item is unchecked, the exporter changes all space characters to underscores.

Both Export Mesh and Export Mesh As… can be invoked either before or after unification. The unification and export process might take several seconds or longer, depending on the complexity of the scene.

UI simboxmenu.png

SIMbox Mesh Exporter Utility

You can also use the SIMbox Mesh Exporter utility to export models. This utility gives you more control over export settings.

  1. Switch to the Utilities tab in the command panel.
  2. Click More…, find the utility named SIMbox Mesh Exporter and click OK.
  3. For faster access, you can add the utility to the initial button set by pressing the Configure Button Set button, at the top right of the utilities rollout.
  4. In the utility rollout, click Properties.
  5. Right-click the root node in the Export List box, and select Add Skinned Mesh.
  6. Select your object from the list and click OK.
  7. Right click the object to add pose or bone animations. You can then define animation names and ranges.
  8. Click Export Selected or Export All.
  9. Alternatively, close the dialog and click Export in the utility rollout.

UI simboxdialog.png

The SIMbox mesh Exporter dialog also has a couple of default material settings.

  • Add DepthWrite off: This adds an attribute in transparent materials that disables writing of polygons with alpha to the Z-buffer. In most cases this solves the problem of rendering multiple transparent polygons but in very specific cases might create unwanted artifacts. Usually there is no need to change it.
  • MipMap Bias: This changes the distance from the camera in which different levels of texture size (mipmaps) are switched in and out. Higher negative value cause sharper textures at a distance but might also cause speckling and shimmering. Higher positive values will cause blurry textures.The current default is -1.