Important Tips:

• Objects may be animated directly using Loc, Rot, or Scale keyframes.  Objects may also be parented directly to bones or other objects, and will inherit the animations of their parents upon export, exactly as they do within Blender.
• Bone envelope deformation on skinned meshes is not supported by the Blender DTS Exporter. Vertex weighting must be used for skinned meshes.   For more info, look here.
• Make sure that every vertex in a skinned mesh has a non-zero weight assigned to it for at least one vertex group. Vertices on skinned meshes that are missing a weight or group assignment may not animate correctly.
• Do not alter an armature in edit mode after you have created animations for that armature, unless you are willing to lose those animations. There are exceptions to this, but you have to know exactly what you are doing.  In other words, make sure that your armatures are more or less finalized before creating elaborate action animations.
• If you need to rotate an armature after creating action animations, do it in object mode and leave the rotation un-applied.  Applying rotation, translation, or scale to an armature object has the same effect as altering an armature in edit mode (will mess up existing animations).

Supported Blender keyframe types

• Loc, Rot, and Scale keyframes and any combination (LocRot, LocScale, etc) for Blender objects and bones.

The Blender NLA Timeline

All sequence that are to be exported to the dts file format should be laid out on the NLA timeline, using either object keyframes or action strips.  The start and end of a sequence are specified by using specially named timeline markers.  Sequences without keyframes such as "Curve Follow" animations and other animation types created via constraints may also be exported by specifying the start and end of the sequence using timeline markers; If an animation causes objects and/or bones to translate, rotate, or scale as the time is advanced, it can be exported regardless of whether keyframes are present or not.

Rest Positions of Objects and Bones

The exporter determines the rest positions of all objects and bones by examining their transforms (location, rotation, and scale) on frame 1 of the NLA timeline.  This means that all objects and bones should be keyed into the desired rest positions on frame 1 of the NLA timeline.  An action strip may be created and positioned so that it covers frame 1 of the NLA timeline in order to ensure that all bones have the correct default transforms after export:

A custom rest pose for armatures that differs from the edit mode bone positions may also be defined in this way.  The rest state of modified meshes is also "baked" by the exporter using the state of each mesh on frame 1 of the NLA timeline; this includes meshes with an armature modifier or armature parent deformation.  If the pose of bones on frame 1 of the NLA timeline differs significantly from the edit mode pose of the bones, skinned meshes may end up looking "pinched".  You should be able to see this in Blender as well when the current frame is set to frame 1.  For this reason it is recommend that the frame 1 rest pose of bones on the NLA timeline should be identical or nearly identical to your edit mode bone positions.  Meshes should also match this pose while in edit mode for easier editing.

Actions and Action Strips

Action animations should be "fenced" at the beginning of each action in order to prevent transforms from other sequences on the NLA timeline from affecting bones in the sequence.  Fencing refers to the practice of keying all bones (even bones that aren't used in the action) into their starting positions on the first frame of the sequence.  Alternately, a one or two keyframe long "rest pose" action strip may be placed between sequences in order to fence them off from each other (you can reuse the same action strip that was used to define the rest pose on frame 1 if you want).

Internal Sequences and DSQ files

Sequences containing a node animation can be exported in one of two ways, as internal sequences (the default) or as separate DSQ (.dsq) files.  Internal sequences are stored within the exported dts file.  Internal sequences can contain any or all of the available animations types in a single sequence (node animations, visibility animations, IFL animations, etc).

DSQ files are separate animation files, each containing a single sequence.  The main use of DSQ files is to share animations between DTS files with identical node structures.  Several characters based on the same armature (skeleton) might share animations, for example.

Sequences that are set up in the exporter to export as DSQ files are each written out to a file with the same name as the sequence, for example, "myAction.dsq".  All DSQ files are written out to the same folder as the exported dts file.  While DSQ files can technically contain animation types other than node animations, this is not officially supported by TGE or TGEA and is not recommended.  The exporter will not prevent you from exporting IFL or Visibility animations to a DSQ file along with a node animation, but you may run into problems.

DSQ files must be associated with the individual DTS files on which they will play back.  This association is made using Torque's scripting language (Torque script).  If the "Write Shape Script" option is enabled on the exporter's general panel, a basic shape script will be written out for the exported DTS file that makes this association.  The generated script will not automatically cause your animation(s) to play in the engine, however.

Node sequences and excluded nodes

When nodes in an object or bone hierarchy are excluded from export via the exporter's Shape->Nodes panel, any child objects or bones are automatically re-parented by the exporter to the next highest node in the hierarchy.  The exporter does its best to keep animations looking the same when nodes are excluded.  Objects or bones that are scaled during a sequence should not be excluded from export, as this may cause problems with exported animations.

When exporting DSQ files, don't exclude nodes whose direct children are animated if those nodes are not also excluded in the DTS file(s) that the DSQ sequence will be used with.  If a DTS file contains a different node hierarchy than the DTS file that was used to create the DSQ animation, animations will likely be screwy when loaded for that model.

Blender keyframes and DTS keyframes

The Blender DTS Exporter examines the actual positions, rotations, and scales of all objects and bones during an animation instead of relying solely on Blender's IPO motion keyframes and curves.  This allows for easy export of sequences that are affected by or created using constraints; without requiring any "baking" of the animations or or other special setup work.  The animations that you see on the screen in Blender should be nearly identical after export.

Keyframes in a DTS or DSQ sequence are always evenly spaced over the duration of the sequence.  When a sequence is exported to a DTS or DSQ file, every whole numbered Blender frame becomes a keyframe in the exported sequence.  DTS and DSQ animation "'tween" or in-between frames are calculated on the fly in the Torque game engine using fast linear interpolation.

It is important to note that the Blender DTS exporter can only sample object transforms on whole-numbered (integer) frame numbers; it is therefore a good idea (but not required) to align Blender keyframes to whole numbered frame positions when creating and editing animations.

The exporter determines whether or not keyframes will be exported for a given object or bone by checking to see if the object or bone has moved from its rest transform as defined on frame 1 of the NLA timeline.  Explicitly keyframing an object or bone in Blender does not necessarily result in that object or bone having keyframes in the exported animation.  If an object or bone never moves, rotates, or scales during a sequence, no keyframes will be exported for that node in that particular sequence.

Blender animations and keyframe density

The DTS exporter samples only whole-numbered Blender frames.  Torque calculates 'tween frames using linear interpolation.  Because of these two factors, animations may look a bit different in Blender than they do after export.  The following example should provide an understanding of how these differences arise and how to correct animation problems that may result from them.

Keyframe density case study - Piston and wheel

A piston is connected to a turning wheel.   Five keyframes are used to animate the piston and the wheel:

The five keyframes are evenly positioned on consecutive whole-numbered frames in the Blender NLA editor.  The object transforms at the first keyframe are identical to the object transforms at the last keyframe; the sequence is cyclic.  The duration of the sequence is set to 4 seconds via the exporter user interface.

After export, the wheel is seen to rotate at a constant speed in a perfect circle.  The tip of the piston arm, however, moves in a pattern that more resembles a square than a circle:

(animated gif, repeats at 15 second intervals)

Translated objects, such as the piston arm, will move in a straight line between each exported keyframe position (whole-numbered Blender frame).  Objects which are rotated, such as the wheel, will rotate smoothly and at a constant speed between keyframes.  Children of rotated objects or nodes will also rotate at a constant speed, inheriting the rotation of their parent and keeping their offset relative to the parent.

By adding more keyframes to an animation and keeping the duration constant (this is where the "duration lock" button on the sequence properties panel of the exporter comes in handy), it is possible to increase the precision of the animation.

Piston arm animation path for 8 frame sequence (red line) (4 seconds @ 2fps)	Piston arm animation path for 16 frame sequence (red line) (4 seconds @ 4fps)

The more keyframes that are used, the more accurate the exported node animation will be.

Note: The recommended frames per second range is between 15 and 30 FPS.  Setting the FPS number for a sequence at too high a value will cause unnecessary stress on hardware and may cause Torque to skip frames when playing back the animation.

For best results, sequences should be planned to have a certain duration and FPS rate before they are created.  Keep in mind that the recommended FPS range for an exported sequence is between 15 and 30 FPS.  If you have a walk cycle that should take 2 seconds for each loop of the sequence to complete, the frame range on the NLA timeline for that sequence should cover no more than 60 frames.  If you can make the walk cycle work with only 30 frames for a 2 second animation (15 fps), all the better.

If an animation cannot be made to work at 30 FPS or lower,  the keyframe positions and interpolation curves may need to be reworked in order to get acceptable results.  Keep in mind that animations are sampled on every whole numbered frame in the specified range; keyframes and other important points or poses in an animation should be shifted so that they occur on whole numbered frames if possible.  The minimum and maximum extents of a given motion should be placed on whole numbered frames, for example.

Cyclic Animations - dead space and automatic removal of the last frame

For cyclic animations in the DTS or DSQ format, the frame distribution looks like this:

The above diagram shows how the frames are distributed for a 4 frame cyclic dts sequence with a duration of 4 seconds.  When the exporter examines your cyclic sequences in Blender, it checks whether or not the first frame of each cyclic sequence is identical to the last frame of the sequence.  If the first and last frame of a cyclic sequence are identical, the exporter automatically removes the last frame from the sequence (preserving the sequence duration).  When the exporter removes the last frame of a cyclic sequence, the following message is written out to the export log file:

    Loading sequence 'test'...
       Frames: 5 
       Animates: loc rot 
       Note: Duplicate frames removed,  (was 5,  now 4)

This is a good thing because it prevents the "dead space" issue, in which a sequence is seen to pause or "hitch" at the start/end of its playback loop.

The exporter will not remove the last frame of a cyclic sequence if the node transforms for the last frame of the sequence are not exactly identical to the node transforms for the first frame of the sequence.  When the exporter fails the remove the last frame of a cyclic animation, the resulting frame distribution looks something like this after export:

It is possible, but difficult, to create a cyclic sequence that loops without pausing or hitching without relying on the exporter's removal of the last frame; therefore no warning is given when the exporter fails to remove the last frame from a cyclic sequence.  If you experience difficulties with hitches or pauses in a cyclic sequence, it is recommended that you duplicate the keyframes from the first frame of the sequence and copy them to the last frame.  Relying on the exporter's automatic removal of the last frame is usually much easier than trying to "stop short" with your last frame.

Note: The "FPS" display in the exporter's Sequence Properties panel may differ slightly from the FPS display in Torque Showtool Pro for cyclic animations that have had their last frame automatically removed by the exporter.  Don't panic!  It's mainly just a philosophical issue regarding how keyframes are counted in cyclic animations.  The FPS numbers are calculated by Showtool Pro and the exporter separately; no FPS value is actually written out to the dts or dsq files.  The duration of the sequence is unaffected by this difference in FPS calculation and will be the same in the exporter's user interface as it is in showtool pro.  Your animations are playing back at the right speed, so try not to get too hung up on this :-)