Torque Exporter Plugin for Blender

Introduction

The Torque Exporter Plugin for Blender is a set of python scripts that allows one to export .dts shapes from blender scenes in .blend files.
The exporter currently supports many of the core features of the DTS format - including bones, meshes, skin weights, sequences, ground frames, triggers, and visibility animation.

Please note that the Torque exporter plugin is still under development, and as such, you may encounter bugs whilst using it. If you wish to report a bug, use the bug tracker at the exporter project page, or create a thread on the Garage Games blender forums.

Requirements

Requirement

Description

Blender 2.43+
Required by the exporter scripts to run.
Python 2.3, 2.4 or 2.5
Required to run scripts in Blender.
VTK + Python Bindings
Optional; Allows more efficent triangle strips to be generated.

Installation

  1. Use one of the supplied installer scripts to install the exporter.
  2. If the script failed, copy all files and folders to your blender scripts directory.
  3. Run blender to verify that the "Torque Shape (.dts)..." item is located on the "Export" menu.
  4. Linux users will need to set the executable flag on InstallScripts.sh using the command "chmod +x InstallScripts.sh" (without quotes) before it can be executed.

Installation Folders

Platform

Script

Default location

Windows Install Scripts.js [Blender Installation Directory from Registry]\.blender\scripts
Mac OSX Install Scripts.scpt ~/.blender/scripts  or  /Applications/blender.app/Contents/MacOS/.blender/scripts
Linux InstallScripts.sh ~/.blender/scripts

How-To

The exporter relies on certain objects to be present in your scene, and makes use of the parenting feature of blender to determine how to structure the .dts.
The example shape located in example.blend contains a working example of how to structure content for exporting via the exporter.
The example also demonstrates what will not get exported by the exporter.

Existing content can easily be structured to export with the exporter.

All objects parented (directly or indirectly) to the Detail / Collision markers will be included in the export in the according detail / collision level.

The first detail level (the one with the highest size) is used as a template by the exporter.
All other objects in the remaining detail levels must be named after the objects in the first, and any stray objects will be discarded with a warning.
The exporter determines the template(or DTS Object) name by splitting the object's name using a ".", e.g.:
"myHead" is associated with the DTS object "myHead"
"myHead.001" is associated with the DTS object "myHead"
"glassWindow.001_Sort" is associated with the dts object "glassWindow"
... and so on.

NOTE: Using Emptys for the markers is preferred.

Sequences (Actions)

For sequences, the exporter looks for the Action's in blender and extracts the necessary keyframe data.
The exporter supports loc, rot, and size animation of bones.

An additional feature of the sequence export is the support for "ground frames", which are used by torque in player animations. The basic idea is that they track the movement and rotation of the object in an animation.

To Export Ground Frames, the "Ground Frames" option needs to be set to above 0. Select the number of groundframes to export (sampling rate), and make sure you have an object called "Bounds" somewhere in your scene (NOTE: it does not need to be attached to the shape empty - e.g. it could be attached to your armature bones, or out in the middle of nowhere).
The "Bounds" object can also act as an alternative set of bounds for your shape. for this to happen, the object needs to be of type "Mesh"

There are two options available for animating the bounds when exporting ground frames.  If you only need one sequence with ground frames, you can keyframe the bounds object directly.  If you would like to export more than one sequence with ground frames, you can parent your bounds box directly to a bone.  The exporter will then pull the ground tranform data from that bone instead of the bounds mesh object, thus allowing for separate ground frame animations for different action sequences.  Since the ground frames are pulled from the raw transforms, make sure that your bounds box and/or bone are axis alligned.

The exporter also supports "blend" animations which are additive in nature.  In order to export a blend animation, select the desired sequence in the exporter's sequences tab.  Press the "Blend" button next to the sequence name.  Two new options will appear on the right allowing you to select the "reference pose" for your blend animation.  The reference pose can be chosen from any frame of any of the available actions.  The action containing the reference pose does not need to be exported.

Finally, the "Sample Frames" option tells the exporter how many frames to export out of the total frames present in the Action. This defaults to the amount of frames in the Action, but you may wish to decrease it to save space in your shape. However, if you do this, you may loose precision.

A new feature to the exporter is the ability to animate the object visibility, via Material ipos.
To enable this, enable the "Mat Anim" option and select a starting frame. The exporter will then go through all the Materials assigned to your meshes and use their ipo curves(specifically, "ALPHA") to create an DTS Object visibility track for the sequence.

NOTE: the exporter will determine the material associated with a DTS Object(see next section) as the first material it finds when exporting the first mesh of the DTS Object.

The exporter also allows you to export animated collision meshes.  This is accomplised by setting a "copy location" constraint on the collision mesh with an armature bone as the target.

Texturing/Materials

Texturing your model is accomplished by UV mapping one or more image textures to a mesh.  The exporter will automatically generate a default material based on the name of the image files that are used.  Options for each material can be found under the "Materials" panel of the exporter GUI.  The texture selection pulldowns in this panel are populated using the names of images that have been loaded in the UV/Image editor

If you wish to use the same base texture for multiple materials, add ".IGNORE*" to the end of the blender image name (ex: "myTex.IGNORE01", "myTex.png.IGNORE.001", etc.).  Just prior to export, the exporter will strip off the "IGNORE" portion of the material name and anything after it.  This allows for the export of multiple materials with the same (base texture) name, but different properties.  When generating a TSE (TGEA) material script for a material containing "IGNORE", only the period delmited section starting with "IGNORE" is stripped from the script material name.  For example, "myTex.IGNORE.001" would generated a TGEA material called "myTex.001" with a base texture of "myTex".

 If you wish to animate material visibility, you'll need to perform the material setup the old way, as described below.


Texturing/Materials (Old Setup)

These instructions are valid for material setup prior to version 0.96 of the exporter.  The exporter will draw it's default material settings from these options when it is initially run, to ease the transition to the new material system  If your models are not UV mapped, however, you will need to UV map them prior to exporting.

In order to apply textures to the model, one needs to assign one or more blender materials to a mesh. In addition, the mesh has to have a UV map. The name of the material in blender corresponds to the texture torque loads. e.g. if you had a material called "Bob", torque would try to load "Bob.jpg" or "Bob.png" as the texture.
NOTE: You should ensure that your Material contains at least 1 texture channel which contains an Image texture for certain options to be taken into account.

Since the properties of materials you can assign in torque itself are not as sophisticated as the ones in blender, the exporter guesses many things, including :

Additional Options

From the exporter gui, you can also toggle which bones to export on the "Armatures" tab.
However, keep in mind that if you exclude a certain bone, all of its child bones will be excluded as well, even if they have not been specifically excluded.

Any options not covered in this document will either be covered in other documents, or on the blender forums referenced from the resource page.

License

Copyright (c) 2003 - 2006 James Urquhart(j_urquhart (at) btinternet.com)

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contact

James Urquhart
E-Mail : j_urquhart (at) btinternet.com
Joseph Greenawalt:
E-Mail : jsgreenawalt (at) gmail.com