AAM exporter for Blender

From VRwiki
Jump to: navigation, search

This page describes a Blender script that allows to export 3D data from Blender to XVR's AAM file format.

The AAM exporter for Blender in action.



The Blender Python API is constantly evolving, so it is advisable to version-match the script in order to avoid unexpected failures. The current version of the script has been tested against the latest Blender version at the time (2.48a).

The requirement of a full Python install has been relaxed since version 0.06.

Getting the exporter

The exporter is a Python script. Download links:

Installing the exporter

To install the exporter, just drop it in the scripts directory, which is usually placed in C:\Program Files\Blender Foundation\Blender\.blender\scripts unless you decided to install it in your home, in which case you should find the .blender directory among your documents; in Vista that would be C:\Users\YOURNAME\AppData\Roaming\Blender Foundation\Blender\.blender\scripts

Alternatively, in Blender, go to the File Paths tab, in the User Preferences window, and select a custom additional script directory in the Python text field. After saving your User Preferences (from the File menu or pressing CTRL+U), it is advisable to reload the program.

Afterwards, the AAM exporter should be available in the File > Export menu, as "XVR AAM format (.AAM)".

Running the exporter

If correctly installed, you can find the script in the usual File > Export menu, as "XVR AAM format (.AAM)".

The operation is pretty straightforward. The exporter operates only on selected meshes. A summary of the available options follows.

Mesh Options

World coords
if set, the selected meshes are exported in their world coordinates; otherwise, local coordinates are used
As character
if set, the selected meshes are exported as a CVmCharacter; this means several things:
  • the resulting AAM file must be loaded as CVmCharacter instead of CVmNewMesh
  • hierarchical information (parenting) is preserved
  • the World coordinates option is ignored; if not set, and there is a single root object, and no animation is to be exported, the root object is moved in the world origin
As avatar
if set, the selected mesh is exported as a CVmAvatar:
  • only one mesh at a time may be exported this way
  • this option and the previous one are mutually exclusive

Animation Options

Export animated
if set, IPO animations are exported:
  • as multiframe meshes if a mesh is being exported; this means that a complete vertex list is saved for each frame (please note that this leads to huge files; nonetheless it is useful in some circumstances)
  • as keyframed animation if a character is being exported (that is, Export as character i set)
  • please note that only sampled animation are supported right now; this means that position, rotation and scale of each component of the subset is saved for each frame; bezier interpolated values are coming
  • please note that this option is incompatible with the As avatar option
Max frames
if set, animations are exported only until this frame; it's not possible to change the first frame currently

Material Options

White texturized material
if set, the diffuse component of a texturized material is set to white, so that XVR does not blend the texture with the underlying color
Force jpg & png extensions
if set, each image file named in the output aam file has its extension renamed to jpg or png, since other formats are not supported in XVR; please note, however, that the actual image files are not converted and must be converted separately
Force dds extension
if set, each image file named in the output aam file has its extension renamed to dds, which is a compressed texture format that optimizes load times; please note, however, that the actual image files are not converted and must be converted separately (for example using the XVR Texture Converter utility
  • overrides Force jpg & png extensions

Useful tips

Texturing and UV mapping

In Blender, a material may specify a texture in two different ways:

  • TexFace option - Shading Panel Group (F5) > Material Panel
In this case, a UV channel has to exist (create one in Editing (F9) > Mesh > UV Texture New or just enter UV Face Select mode); now, enter Face Select mode: it is possible to assign an image to each selected face by just loading the image or selecting it from the popup menu.
See also the Blender documentation for more details.
  • Texture options - Shading Panel Group (F5) > Texture/Map Input/Map To panels
In this case, multiple textures with multiple mapping modes can coexist, and affect not only colors but also many other quantities.

Both options can coexist in Blender.

Having said that, please keep in mind that:

  • only UV-mapped textures are exported (but common modes such as Orco are easily reproducible in the UV editor using the unwrapping tools)
  • in Blender, only TexFace textures are fully displayed in 3d view (textured modes); other textures are sampled per vertex
  • only one texture layer is currently exported
  • if TexFace is enabled, TexFace textures are used
  • otherwise, the first texture channel affecting color is used
  • up to two texture channels are exported if available (requires Blender 2.43 or above)
  • the first texture is the "texface" one if available; otherwise it's the first texture affecting color in the active texture channels
  • the second texture is the first texture affecting color in the active texture channels, or the second if no "texface" texture is available
  • multiple UV layers are correctly handled.


In Blender, there are two different ways to specify smoothing:

This is the "traditional" method, and involves setting the smooth or solid flag for each individual face. In tricky situations, it may be difficult to achieve good results.
This is a recent method. It splits the mesh according to some parameters, both global (such as edge angles) and local (such as edges marked as sharp).

Both methods are supported, but given some differences in handling smoothness in Blender and XVR, the second method is generally suggested. Furthermore, since the second method results in superior quality and easier handling even in Blender, support for the first method may even be discontinued in the future.


Modifiers are handled by applying them before exporting. Be careful because some modifiers such as subsurface can potentially create very memory-hungry meshes. Other problems may arise when other modifiers, such as armatures, are applied. For skinned meshes, this is almost certainly not what you want. In that case, we don't apply any modifier.

Meshes with armature modifiers, exported as avatars, are treated differently from the rest. Please report any issues.

Known limitations

Missing AAM features

  • Interpolated Character animations are not supported yet.
  • Environment maps are not supported yet.

Missing Blender features

  • Please note that texture coordinates are exported only from uv-mapped objects.
  • Procedural materials and most of other materials features are not exported; this is somewhat inevitable and not due to the script itself as there's no direct OpenGL support to those - although it would be nice to export them as GLSL shaders.
  • The same holds true for node materials.
  • Skinned animations are not supported yet (work on preliminary support is ongoing) (added in 0.7)
  • The script currently supports only one texture layer (added in 0.7)

Other shortcomings

  • Development so far has not been concerned in the least with optimizations. This means that the script is certainly slower than it could be possible, and maybe even memory-hungrier. This issue will be addressed in future releases, but in practice it is already usable as is.

Bug reports

Please post bug reports in the XVR user forums.


Ver. 0.7a

Version 0.07a.20081215

  • fixed bug: UV textures not referring to a specific channel would crash the exporter

Ver. 0.7

Version 0.07.20071031

  • added support for avatars
  • added support for secondary textures (lightmaps) and multiple UV layers (requires Blender 2.43 or higher)
  • fixed bug: exception when exporting a character hierarchy including empty meshes

Ver. 0.6a

Version 0.06.20070613

  • fixed bug: exception when exporting mesh with uv coordinates but no associated image
  • fixed bug: wrong shininess values exported (caused wrong shading in XVR)

Ver. 0.6

Version 0.06.20070508

  • removed dependencies from external Python modules
  • [GUI] removed double "export frames" option, reduced to one "export animated"
  • [GUI] improved Pop Up menu wording
  • fixed bug in materials handling that could lead to a wrong number of material groups
  • fixed bug in character animation that prevented animations from starting
  • better handling of texture names
  • restore original "current frame"
  • internal code refactor

Ver. 0.5

  • support for animated AAM Characters (sampled animation)
  • fixed bug in smoothing group handling

Ver. 0.4

  • support for non-animated AAM Characters

Ver. 0.3

  • support for multiframe (animated) AAM Meshes
  • added "force DDS extension" option

Ver. 0.2

  • added wait cursor
  • added "white material if texturized" option
  • added "force jpg and png extension" option
  • added "world coordinates" option
  • fixed bugs in materials assignment

Ver. 0.1

  • support for multimaterials
  • basic AAM support