DTS vs. DSQ: The Technical Side of Game Art

UPDATES!

• Several things were pointed out as being unclear or incorrect, so I have fixed them below. A thanks goes out to Matt Fairfax and Logan Foster for the corrections!
• Updated a few of the images to reflect the article changes.

ORIGINAL ARTICLE
I've been working with Torque now, and many of its versions since 2001. I've learned a lot over this period of time, and not just about the engine. I've learned things about game development in general. There's a lot more that goes into than people realize. Even the art side of development is highly technical. That said, I'd like to post some of what I have learned in Torque here to help others.

A recent problem I've run into involved DTS and DSQ files. It's one thing if you only need to animate transform-based attributes, such as object rotation, position or scaling. For that, DTS will do everything you need. It's when you have a model that requires vertex, texture, visibility or morph animation that you need to use DSQ. This is where my problem arose, since I've been avoiding this issue like the plague since I've started with Torque. Furthermore, I finally found my answers, but they were so spread all over the place that I figured it's time for all of this information to be in one place. I'd also like to thank the GG community, as many of you have helped me throughout the years.

Before I begin, I'd like to mention that in this article I use 3ds max 2008, and assumes you know how to model, texture, animate and rig. If not, you might need to brush up on those skills first. I'd also like to point out that there are more ways to do this than is written here, but I am going for a "simplest and best practice" approach. With all that out of the way, let's begin.

There are 3 main components to a rigged/skeletal animation for Torque. They are:

1. DTS File - This is the mesh itself that will be animated.
2. DSQ File - This is the animation file that corresponds to the above DTS.
3. Script - This is what allows the object to animate within Torque.

For our purposes, we will be creating an animated flag, since this requires a somewhat complex animation (hence the reason for using the DSQ). First thing's first, the DTS File.

The DTS File

Here we have our mesh to be animated. However, it requires more than just the mesh. It requires a somewhat specific hierarchy, which is quite different from the typical DTS hierarchy. There are also a few specific requirements of the mesh itself as well.

For the mesh, I prefer it to be an editable mesh, not an editable poly. It is possible to export using Editable Poly, but this can cause the exporter to crash max. Secondly, it is recommended that the Skin modifier be on top of the modifier stack, and is recommended that no other modifiers be present. Again, this is not a requirement, but is good practice. This is because the skin modifier affects the underlying mesh, and could affect other modifiers if they are present, yielding sometimes unpredictable results. So, your modifier stack should look something like this:


Also, it may not be linked to anything else in the scene. It needs to be in the scene root (or not linked to anything else). The mesh still needs to end in a number, which represents the Level of Detail (LoD) of the mesh, unless you are using the Multires modifier. However, since Multires is outside the scope of this article, I'll table that discussion for now.

The "bounds", or bounding box, should generally be linked to the base of the hierarchy root. In this case, it should be linked to our "user" node (more on that in just a moment). This is not necessary for static objects, but is still good practice.

Next, my technique involves the creation of a standard "dummy" object, which I have arbitrarily named "user". It may be named anything, so long as it does not end in a number.

Next, I link the bone structure to the "user" dummy object. I then create another dummy object to act as the detail node. This must be named "detail#", where # is replaced by the detail number you used at the end of your mesh above. This also gets linked to the "user" object.

You should now have a rig that looks something like this:

That's all that's required for the DTS mesh file.

Also note that this file does not require the bones to be animated, nor does it require an animation sequence node.

Save the file in max, then export it using the "whole shape" button in the standard exporter. I exported mine to "art/shapes/animatedObjects".

The DSQ File

This file is pretty much the same as the last, with a few exceptions. What I prefer to do is save the mesh file as a new file, named slightly different to denote it as an animation. Working from there, we now need to animate the bones. Once this is done, one needs to create a sequence node. This is different from a dummy object, so I'll detail it below.

Create the Sequence Dummy Object:

Make sure to name the sequence node what you intend to call the animation. For this example, I'll name it "ambient".

Open up the Curve Editor from the top toolbar.

Once in the Curve Editor, do the following 3 things:
[ol]

Select Add Keyframe from the toolbar.

Locate "Object(Sequence II)" in the list, then select "Sequence Begin/End" from under it.

Add keyframes at the beginning and end of the animation.[ol]

In my case, the animation goes from frame 0 to frame 15 (16 frames of animation). So my first key is on frame 0, while the last is on frame 15. This will vary depending on the length of your animation, but it necissary so Torque can detect what frames to use for your animation.

Here is a picture of the Curve Editor:

One last point I need to make before we move on is that the Sequence object should be within the bounding box as well as in the scene root (not linked to anything). It is not a requirement that the Sequence node be placed within the bounds box, but I find it to be good practice because it keeps the scene cleaner in my opinion. So, your hierarchy should be very similar to the one for the DTS, but with an additional node added. it should look something like this:


Export using the "Sequence" button. Again, I exported mine to "art/shapes/animatedObjects".

Okay! That's all for the modeling section! One more step to go to get this working in game!

The Script

First off, I should mention that much of this section is not needed when using Torque 3D, but is required for TGE/A. For a brief explanation of Torque 3D's usage, see Matt Fairfax's post below.

There are several approaches to do this, but this is the one that I have found to work best for me. First, create a folder in the "scripts/server/" directory called "animatedObjects". Within that folder, create a new .cs script file called "animations.cs". Open up that file and add the following code:

// Datablock Definition.
datablock StaticShapeData(FlagAnimDB)
{
   shapeFile = "art/shapes/animatedObjects/flaganim.dts";
   category = "AnimatedObjects";
};

// When the shape is added to a scene.
function FlagAnimDB::onAdd(%this,%obj)
{
   %obj.playThread(0,"ambient");
}

// When the shape is loaded into memory.
function FlagAnimDTS::onLoad(%this)  
{  
   %this.addSequence("art/shapes/animatedObjects/flag_ambient.dsq", "ambient");  
}

// Set up the shape for use with DSQ animations.
singleton TSShapeConstructor(FlagAnimDTS)
{  
   baseShape = "art/shapes/animatedObjects/flaganim.dts";  
};

Replace "animatedObjects" with the name of the folder you saved the dts and dsq in. Once this is done, go ahead and save the file and close it.

One last thing is that we need to reference the new script file so it executes. Open up "scripts/server/scriptExec.cs" and add the following code below "exec("./players/player.cs");":

// Load up our custom animations script.
exec("./animatedObjects/animations.cs");

Now you should be able to load up a level and drop in a shape from under the "AnimatedObjects" category, and it should automagically animate when dropped in.

I hope this article has helped you to be able to get rigged, animated shapes into Torque. Comments and feedback are welcome and encouraged.

Happy Torquing!