Ultimate 3D model file export plugin

The Ultimate 3D model file export plugin for Blender gives you the possibility to export models directly from Blender 2.49 or Blender 2.59 (in later or earlier releases it may or may not work, just try it) to the Ultimate 3D model file format (*.u3d), which can be used with the 3D engine Ultimate 3D. If you are interested in using the Ultimate 3D model file format for one of your own Ultimate 3D independent applications have a look at its chunk descriptions. The format is a quite simple binary format and it is well-documented. A viewer for *.u3d files is also available. The use of the export plugin is quite simple. This document will describe the process in detail.

Installing the plugin in Blender 2.49

The installation of the plugin is quite simple. The download contains a file called io_export_u3d_blender249.py. This is a Python script containing the export plugin. Copy it to %BlenderDataDirectory%\.blender\scripts. The data directory of Blender is either the installation directory (e.g. C:\Program Files\Blender Foundation\Blender) or a user specific AppData directory (e.g. C:\Users\Christoph\AppData\Roaming\Blender Foundation\Blender). Once the file is copied you need to start Blender (or restart it, if it was already running). The menu File->Export should contain an entry called "Ultimate 3D model file export (*.u3d)" now. If so the installation has succeeded. If the plugin does not work the reason usually is that it uses several Python modules, which do not come with Blender 2.49. In this case it will say "Python script error: check console". To fix this go to the Python download site and download Python 2.6.x. In most cases this fixes the problem.

Installing the plugin in Blender 2.59

In Blender 2.59 the installation is even simpler. The download contains a file called io_export_u3d_blender25.py. This is a Python script containing the export plugin. Open Blender 2.59 and go to File -> User Preferences to open a user preferences window. In this window navigate to Add-Ons and click the Install Add-On button at the bottom. In the file selector that shows up select the file io_export_u3d_blender25.py (you have to unzip the download somewhere). The export Add-On is installed now and you can enable or disable it at any time, by checking or unchecking it in the list of Add-Ons. It is called "Ultimate 3D model file export (*.u3d)" in this list.

The features of the exporter

The export plugin is quite versatile and should offer enough features for most purposes. It can export the following data:

Usually this is all data a game developer needs, but Blender can handle a lot of additional information, which can not be exported with this plugin. I want to state some things that can not be exported explicitly here:

Exporting models from Blender 2.49

Exporting models from Blender 2.49 is a simple process once the plugin is installed (see above). In Blender navigate to File->Export->Ultimate 3D model file export (*.u3d) and click it. A pop up with options will appear. Set them as appropriate for what you want (see below) and click Ok. Then a file selection window will show up. Simply choose the file you want to export to and click "Export *.u3d model". You will not be warned, if you try to overwrite an existing file. If everything works out fine you will see a small pop up message, telling you that exporting has succeeded. If it has not succeeded check the console window for more information.

Exporting models from Blender 2.59

Once the add-on is installed and enabled (see above) exporting models from Blender 2.59 is very simple. In a Properties space go to the scene buttons and locate the panel labeled "Ultimate 3D export". Set up everything correctly as described below (usually the default settings are fine), define the output file and click "Export". During export Blender freezes. It is recommended to toggle the console window on before export. It contains information about the progress of the exporter. If no error message pops up, a short note in the Info space will inform you that exporting the model was successful and you can find the *.u3d file at the specified location.

Export options

Usually the default options of the exporter are fine. However sometimes particular features may cause problems or you may not want their result. Therefore you can change settings. Here is a list of all available options:

Input settings

Selection only
If this option is enabled the plugin will export only objects that are currently selected. This is useful if your file contains many components that are not meant to be exported, e.g. older versions of the model on other layers. If it is disabled all objects in the current scene will be exported (default). Layers are disregarded.

All UV textures
If this option is enabled all UV textures will be exported. This can only work if all meshes, which are to be exported, have the same number of UV textures and the same names for their UV textures. Otherwise the option gets disabled automatically. The plugin outputs the mapping of UV layers to texture coordinate indices to the console window. Besides it makes material textures use the right texture automatically. This feature can be very useful for exporting models with baked textures, especially for light maps.

This option can be set to three values. If it is set to "Ignore modifiers" all modifiers except for armature modifiers are ignored and only mesh objects can be exported. Otherwise the exporter exports meshes with all modifiers applied. More generally spoken it exports all meshes just like they are displayed in Blender. Armature modifiers are the only exception. As a consequence of this all object types, that are visualized through meshes can be exported. Those are mesh, surface, curve, meta and text. If the option is set to "Use modifiers (realtime settings)", modifiers are exported using their settings for interactive display (default). If the option is set to "Use modifiers (render settings)", the modifiers are applied using their settings for rendering.

Animation settings

This option defines how animation data is retrieved. It can be set to four values. If it is set to "No animations", animations are not exported at all, armatures are ignored and armature modifiers are not treated in a special way. If it is set to "Actions from curves", all actions are exported by reading them directly from the IPO- or F-curves. If you use this option constraints are ignored. If it is set to "Actions with constraints", all actions are exported by playing them back and recording them. This way the effects of constraints can be exported. If it is set to "NLA with constraints" the current animation of all objects (i.e. their NLA) is played back, recorded and the result is exported. This includes constraints as well. The animation of the output should be identical to the animation in a render.

Eliminate unused bones
Armatures often contain many bones, which are used exceptionally for controlling other bones, especially if you use inverse kinematic. Since these bones do not effect any geometry, they can be eliminated without losing relevant runtime information. If this option is checked the exporter does precisely this. It searches for bones, which do not effect any geometry and eliminates them. Their animation gets applied to the animation of all existing child bones. This can drastically reduce the number of bones that need to be processed at runtime, leading to an increased performance. On the other hand it increases the time that is needed for export and leads to a slight loss of precision in your animations. If this option is not checked the exporter exports all bones (default).

Max key distance
If this value is zero the exporter creates key frames exceptionally at frame values at which the corresponding action or NLA defines a key frame (default). This leads to small files with few keys and a fast export. However Blender and Ulimate 3D use different methods for interpolation between key frames and thus the exported results are not perfectly precise. You can increase this precision, by exporting more key frames. If you define a positive value for this option (it is recommended to use integers), it gives the maximal number of frames between two neighboring key frames. The exporter creates additional key frames as needed. This increases the time needed for export and the size of the files, but it also increases the precision in animations. Setting this option to 1.0 makes the exporter create a key for every frame.

Speed factor
This option defines a factor, which is applied to the frame values of all keys in the exported model. Thus it changes the speed of the animation. Smaller values yield a greater speed.

Output settings

Use v2.0 (U3D 3.0)
If you enable this option the plugin will not use version 1.0 of the model file format for exporting (default), but version 2.0. Version 2.0 is used by Ultimate 3D 3.0 and Ultimate 3D 2.x can not load it. Ultimate 3D 3.0 can also load version 1.0 of the model file format, so usually it is best not to use this option. Only if you are working with some application, which supports only version 2.0, it is reasonable to use this option. If you are not me that is unlikely. Both versions of the model file format are documented (documentation of version 1.0 and documentation of version 2.0).

U3D file
The file to which you want to export. Note that the exporter will overwrite it without prompt.


If anything goes wrong with the exporter please read this document first. Make sure that the information you want to export can be exported and that you have selected the right options and installed the exporter correctly. If it is still not working there are several possibilities to report this. The easiest way is to post a report on the Ultimate 3D Community. Alternatively you can contact me by email at admin@Ultimate3D.org or through the contact form on Ultimate3D.org. I am thankful for any bug report. Just make sure that you include the relevant information. What is not working, what is the console output and which Blender version are you using? It is also very helpful, if you include the Blender file in the bug report. You can rely on the fact that I will not use it for anything other than debugging purposes.

Last updated: 6th of September 2011

© Christoph Peters. Some rights reserved.

Creative Commons License XHTML 1.0 Transitional