Formats

ShiVa's primary 3D model import format is Collada *.dae. This is an open and very common format found in many Digital Content Creation (DCC) tools today. Industry standard tools like 3ds Max, Maya, Lightwave, as well as open-source tools like Blender and Winds3D pack Collada exporters by default.

Static (unanimated and unskinned) models can also be imported using the *.dwf format. These files are commonly used in Autodesk products and CAD applications, but relatively unknown in common game asset pipelines. If you are a virtual architect who mostly uses CAD, this format option is for you, everyone else should use Collada.

Format Conversion

Even if your preferred 3D tool does not export to Collada directly, there are a number of conversion tools out there that can help you. Here are two of the most well-known converters:

Autodesk FBX tools

This free program converts FBX files into a number of formats and back, including Collada. It has a model viewer and supports animation takes. You can download it for free from autodesk.com/asdk. It runs on Windows and OS X.

Ultimate Unwrap

Ultimate Unwrap 3D (UU3D) has the reputation of being the Swiss Army Knife of model converters. It is not free and runs on Windows only, but supports a very wide range of import formats. UU3D can also attempt to repair broken and ill-constructed model files so that they run well with ShiVa. You can get it from unwrap3d.com in various licenses.

Coordinate System

ShiVa uses the OpenGL coordinate system (+Y axis up). Some modellers do use a different coordinate system, most notably 3ds Max and Blender (+Z axis up). If you are using such a modeller, make sure you flip the Z and Y axis upon import into ShiVa.

Every ShiVa grid unit represents 1 meter. Please scale your models accordingly. If you are making a game about very small or very big things, it might be a good idea to scale the entire game world up/down to "standard human size" - this helps the physics engine a lot.

The ShiVa Object API is designed to deal with models that are oriented in a certain way. -Z is the direction the character should look at, +Y is up, +X is the right hand side.

Animation

Each Animation (walk, run, attack, shoot, ...) should be imported separately as its own independent AnimClip and then added to the model's AnimBank controller.

Animations should be based on a time index of 60 frames per second. Each vertex can have up to 4 bones influencing it (-> weighting).

Bones/Joints are the only supported animation technique for AnimClips. If you want vertex animation/blend shapes, you will have to interpolate individual models through the mesh.morph* API.

Common import errata

Freezing TRS

If your model appears skewed and deformed beyond recognition, you probably forgot to "freeze" it.

Before you export a model, you must make sure that all TRS options (translation, rotation, scale) have neutral values (0 for rotation, 1 for scale), something which most modellers have a function for, like:
- Blender "Apply Rotation" and "Apply Scale" under Object -> Apply
- 3ds Max "ResetXform"
- Maya "Freeze and Reset transformations"
- etc.

Bone displacement

If your skinned and animated model appears deformed and deforms even more during its animation, you probably need to parent your whole bone structure to a root bone that is located at the origin (0,0,0), has no rotation and a uniform scale of 1.

Materials and Shading

Material settings (colors, shading settings etc.) usually do not translate into ShiVa. In case everything you just imported appears to be black, check the material color values. Ambient colors exported by e.g. Maya are black for all materials by default, which is probably not what you wanted.

Also check the Lighting flags, depending on your light setup. Right after the import process, there is no light nor lightning material configuration in the scene, so you have to open your materials and choose the right lighting setup for this scene.

Missing textures

Sometimes, textures are not or cannot be imported. This may have one of the following reasons:

- Procedural materials like e.g. from 3ds Max cannot be exported, but must be baked into a texture map first.
- Your textures have special characters in them.
- Your texture is in a file format ShiVa does not accept. Use JPG, TGA or PNG to be on the safe side.
- The path to the textures is unknown. Make sure you have them in the same directory as your model file.

At any time, you can manually import your missing textures as separate files and assign them to your materials - in case everything else fails.