|
|
|
This document is a general reference guide for using Maya to create shapes and animations for the Torque Game Engine. It will provide some general guidelines for how to prepare shapes and animations for use in Torque as well as provide information regarding the specifics of working with the Maya2DTS exporter.
A File Pack containing the Maya2DTS exporter, dtsUtility.mel, the PNG support plugins for Maya 5 for Windows , sample configuration files, and all files from the tutorials is available for download here:
http://www.dannyngan.com/torque/maya2dts/maya2dts_filepack.zip (~1.6 MB)
Information about the File Pack can be found here:
Some basic tutorials for working with the Maya2DTS exporter can be found at the following URL:
While all screenshots and directions are for Maya 5.0.1 for Windows, most of the information provided here is applicable to Maya 5.0 for all platforms. Platform-specific information will be provided when necessary. Maya 4.5 users may need to make some adjustments to account for version differences.
This document is primarily derived from the Max2DTS exporter documentation written by Joe Maruschak of BraveTree Productions (http://www.bravetree.com). While this document is specific to Maya, much of the information presented here is the same for both 3DS Max and Maya.
Important note:
The Maya2DTS exporter is still in beta. The contents of this document may change depending on the development status of the exporter. Also, the contents of document may not match up exactly with the features available in the publicly available version of the exporter. Until the exporter is in final release, this document should be considered a work-in-progress.
This document assumes a basic level of familiarity with Maya. The majority of the information provided here is designed to help users become familiar with Torque-specific tools and techniques. Where appropriate certain basic information about how to work within Maya has been included. Information on general usage of Maya can be found in Maya's help files (pressing F1 on the keyboard will open them in the user's default web browser).
The exporter is for the most part stable. Like all Maya plugins, it can crash. If it is constantly crashing on export with ALL shapes, the error likely lies not in the exporter, but in your system configuration.
The exporter generates a dump file named dump.dmp in the directory you are exporting to. If your export fails, check the dump file first to see where it is crashing in the export process. Most of the time it is something simple, like spelling the word "bounds" wrong.
If a particular model is continually crashing on export, corrupted meshes, bad texture vertices, or double faces in the model might be the cause. Check the dump file, and if it stops on a particular mesh, do a test by deleting it in the Maya scene file, then try to export again.
After a model is successfully exported, check your shapes in the ShowTool (-show switch) first before bringing them into your game. If it works in the ShowTool but not in the game, the file exported properly and the problem probably exists elsewhere.
What is required for a shape to work "in the game" is not the same as what is required for a shape to export. If your game requires certain nodes be present, a certain naming convention, or certain parameters set a certain way, then get that information and set up the shape accordingly. If your shape works in the ShowTool but not in the game, then it is most likely not the exporter that is at fault.
Some of the tools and techniques outlined in this document (especially the animation setup and usage) require a paradigm shift about how one thinks of setting up shapes. The engine supports a very flexible Non Linear Animation (NLA) system. It is hard at first to grasp, but with patience, one can understand and utilize the tools controllably.
This document is simply a general reference for creating and exporting shapes using the Maya2DTS exporter. It is not a quickstart guide for how to use Maya nor is it a detailed tutorial on how to build and animate shapes for the Torque Game Engine.
Make sure Maya is not running.
Install the Maya2DTS exporter plugin
Place the exporter plugin (maya2dtsExporter.mll for Windows and Maya2DTSExporter.lib for OS X) in the user plugins directory:
Windows: My Documents\maya\5.0\plug-ins
OS X: Home folder, Library/Preference/AliasWavefront/maya/6.0/plug-ins
Install the dtsUtility MEL script
Place the file dtsUtility.mel in the user scripts directory:
Windows: My Documents\maya\5.0\scripts
OS X: Home folder, Library/Preferences/AliasWavefront/maya/6.0/scripts
Install PNG support files (for Maya 5 for Windows only)
Place the file IMFPng.dll in the Maya image plugins directory:
C:\Program Files\AliasWavefront\Maya5.0\bin\plug-ins\image
Place the files libpng12.dll and zlib1.dll in the Maya bin directory:
C:\Program Files\AliasWavefront\Maya5.0\bin
Note: PNG support in Maya 5 is read-only, i.e. Maya will not output PNG files via the renderer.
(IMFPng is written by W.J. van der Laan. Complete source code is available at http://www.fmf.nl/~orion/IMFpng/. See the included readme file in the File Pack for more information.)
All of the necessary files are now installed.
Several items need to be configured to ensure that shapes and animations work correctly with the Maya2DTS exporter.
Ensure that the Maya2DTS exporter is installed and loaded:
1. Launch Maya if it is not already open.
2. Open the Plug-in Manager (Window > Settings/Preferences > Plug-in
Manager).
3. Make sure that both loaded and auto
load are enabled for maya2dtsExporter.mll (Windows) or
Maya2DTSExporter.lib (OS X).
The Maya2DTS exporter is now loaded and will auto-load each time Maya is launched.
The dtsUtility window can be opened at any time by running the following command from the Command Line or the Script Editor:
dtsUtility;
This is what the dtsUtility window looks like:
Typing the command is fairly easy, but it can be quicker by using a custom shelf button.
To create a shelf button for quick access to dtsUtility.mel:
1. Open the Script Editor (Window > General
Editors > Script Editor).
2. In the input area (bottom half of the window), type in the following command:
dtsUtility;
3. Select the text with the left mouse button.
4. Using the middle mouse button, drag the text to the shelf to create a shelf
button.
5. Open the Shelf Editor.
6. Add an Icon Name to shelf button to make it easier to identify.
The dtsUtility shelf button is now created. Clicking the button will bring up the dtsUtility window.
Torque's unit scale is 1 unit = 1 meter. Maya's default is 1 unit = 1 centimeter. To avoid confusion, change Maya's linear units to meters. The unit scale can be changed in the Settings section of the Preferences window. (Windows > Settings/Preference > Preferences).
If the camera's display is behaving oddly after changing the unit scale (e.g. odd clipping), change the camera's near clipping to .001 and its far clipping to 10000.
To access the camera's near and far clipping attributes:
1. Open Outliner (Windows >
Outliner).
2. Select the camera.
3.
Press ctrl-a to open the Attribute Editor.
4. Change the near clipping attribute to .001 and the far
clipping attribute
to 10000.
The default animation frame rate in Torque is 30 frames per second (fps). Maya's default frame rate is 24 fps (also known as Film in Maya). Change Maya's time units to 30 fps / NTSC in the Settings section of the Preferences window.
When changing preferences, make sure to press the Save button before closing the window, otherwise, the settings will not be retained the next time Maya is launched.
You can also configure working units from the DTS > Setup submenu in the dtsUtility window. See the dtsUtility section for more information.
Maya organizes various files associated with scene files into projects. A project is a collection of folders for different types of files. For example, a project workspace may contain separate directories for scene files, textures, rendered images, and exported data.
Maya's default project directory is located in the user's home directory:
Windows: My Documents\maya\projects\default\
OS X: Home folder, Documents/maya/projects/default/
While it is not mandatory to set up custom project workspaces, it is advised that users set up unique project directories for different tasks. For example, there could be one project workspace for a character model, another one for full body animations, and yet another one for blend animations. This will allow the user to load unique configuration (CFG) files for each shape or animation. Also, users will be able to specify default directories for exporting DTS and DSQ files (Torque shape and animation files).
To create a new project workspace:
1. Open the New Project window (File > Projects > New).
2. Specify a Name and Location for
the project workspace directory.
3. Optional: Specify directories for exportDTS and exportDSQ.
If no directories are specified, then the directory containing the Maya scene
file will be used.
4. Optional: Specify directories for scene
files, textures, etc.
5. Click the Accept button.
The project workspace is now created.
To load a project, go to File > Projects > Set. Then choose the project directory.
To edit a project, go to File > Projects > Edit Current.
Using project workspaces might be odd for many artists new to Maya, but once one becomes accustomed to working with them, project workspaces can be invaluable tools in the art production workflow.
Custom exportDTS and exportDSQ locations can be set in the Export Settings dialog box. See the dtsUtility section for more information.
The following sections provide general working tips in Maya as they pertain to creating shapes and animations for the Torque Game Engine.
Mesh Specifications
All meshes must be made up of polygons. You can use NURBS or subdivision surfaces to create your meshes, but they must be converted to polygons prior to exporting. You can convert meshes to polygons by going to the Modify > Convert submenu and then selecting the appropriate conversion type.
All meshes must be triangulated. To triangulate a mesh, go to Polygons > Triangulate.
Build all your meshes according to real-world scale. The Maya2DTS exporter pays attention to the linear working units setting in Maya and will export shapes accordingly. For example, if you build your meshes using Maya's default linear unit of centimeters, a 2 unit tall character will be 2 centimeters tall and will show up in the engine as a 2 centimeter tall object.
Model Cleanup
Check for unnecessary/undesirable holes in the mesh. Turn on Border Edges (Display >Custom Polygon Display options box) to show open polygon edges.
Make sure the mesh's tranforms are clean. If you have scaled or mirrored the mesh during the modeling process, be sure to freeze the scale transforms before continuing with rigging and/or animation.
To freeze a mesh's scale transforms:
1. Select the mesh.
2. Go to Modify > Freeze
Transformations options box.
3. Uncheck everything except Scale.
4. Click the Apply button.
The mesh's scale transforms should now be 1 for all axes.
UVs
All meshes must have UV coordinates in order to export correctly. To check for unmapped faces, turn on hardware texture view (press 6 on the keyboard) and look for faces with a semi-transparent striped pattern. Faces with that pattern do not have UV coordinates applied to them and must be mapped.
Multiple UV sets are not supported. If a shape contains more than one UV set, the shape will not export, and the exporter may crash.
Material Specifications
Lambert, Phong, and Blinn materials are supported.
All materials must use File textures in the Color channel. Procedural textures and material colors are not supported in Torque.
Torque supports JPG, TGA, and PNG file formats. Note: PNG support in Maya 5 for Windows is provided by the IMFPng plugin included in the File Pack.
Image file dimensions must be powers of two (e.g. 256x256, 64x64, etc). Textures do not have to be square (e.g. 64x128).
Multiple textures on a single mesh are allowed.
Transparency
To make an object transparent, the texture on the object must have an alpha channel. The amount of transparency is controled by the image's alpha channel. Applying an image file with an alpha channel to the Color attribute of a material will automatically apply the image's alpha channel to the same material's Transparency attribute.
Two-Sided Materials
Two-sided materials are supported by adding a custom attribute named twoSided to the object. The twoSided attribute is a boolean value that determines whether or not the shape will export with double-sided materials.
This attribute can be added from DTS > Rendering Options > Enable Two-Sided Materials in the dtsUtility window.
Note: Maya's double-sided material rendering setting is ignored by the exporter.
Visibility Animation
Visibility animation is supported by adding a custom attribute named vis to the object. The vis attribute should be a float value with a minimum value of 0 and a maximum value of 1.
This attribute can be added from DTS > Rendering Options > Enable Visibility Animation in the dtsUtility window. enableVis must also be turned on in the matching sequence node.
Note: Maya's visibility attribute is ignored by the exporter. Visibility animations must be previewed in the ShowTool or in-game.
Character Construction
A character can be constructed as either segmented meshes or a single mesh.
Segmented meshes can be setup in a hierarchy or parented to joints.
Skinning/Vertex Weights
Single-mesh characters must be deformed using joint hierarchies and smooth skin binding. Rigid binding and influence objects are not supported.
Vertices on meshes may be weighted to more than one joint at a time. A maximum joint influence of 3 is a good value (this is the maximum number of joints that can affect any one vertex). This is set in the Skin > Bind Skin > Smooth Bind options box prior to binding the mesh to the skeleton.
Morph Animations
Non-linear deformers and blendshapes can be used, but they must be exported as Morph Animations. It is recommended that users do not use morph animations unless absolutely necessary, because morph animations can result in very large files that could impact performance in the engine.
Animation Options
Objects can be animated using almost any animation feature in Maya. This includes IK handles, constraints, set driven keys, and expressions. If custom control objects are used as drivers (e.g. NURBS curves for animation controls on a character), those objects may need to be included in the AlwaysExport list of the scene's configuration file (.CFG).
The Maya2DTS exporter is a plugin that allows you to export shapes and animations for use in the Torque Game Engine. There are two file types that you can export: shapes (DTS) and sequences (DSQ).
A DTS file contains shape and animation data. It is the base format for all shapes. A DTS file contains meshes, detail levels, the bounding box, and all necessary nodes for a particular shape. Animation data is optional but can be included in the DTS file.
A DSQ file only contains animation data and requires a matching DTS file that contains all of the necessary nodes for the shape. There can be multiple DSQ files for any one DTS file. Also, DSQ files can be used on multiple DTS files provided that the animation nodes in the DTS files match exactly.
You can export files using one of several methods. One method is to use File > Export All, and then choosing the file type (exportDTS or exportDSQ) from the file type dropdown menu. This method is the most flexible, because it will allow you to export to a filename and location of your choosing. The Export... button in the dtsUtility window will do the same thing.
You can also use the Export Shape and Export Sequence buttons to export DTS and DSQ files, respectively. Both buttons will export to the DTS and DSQ directories defined in the dtsUtility's Export Settings dialog. By default, both buttons will also use the current scene file's name for the exported files. For example, if the scene file is named myShape.mb, the resulting DTS and DSQ files will be named myShape.dts and myShape.dsq. If you choose to use the Export Sequence button to export multiple sequences, it is highly recommended that you create unique names for each Maya file (see the section on Animating for Torque for more information about multiple sequences). You can override the default names from Export Settings dialog in the dtsUtility window (see below for more information).
The dtsUtility window provides options to speed up and aid you in preparing shapes and animations for export. It is not required for successful creation and export of shapes and animations, but it does simply the process a great deal.
The buttons in the dtsUtility window have the following functions:
About: Opens a window containing author names, links, and copyright information.
Export Control
Export...: Opens the Export dialog box.
Export Shape: Exports the current scene as DTS file to the exportDTS directory.
Export Sequence: Exports the current scene as a DSQ file into the exportDSQ directory.
Export Settings.. : Custom configure export file names and directories. Options are available for scene-specific settings and global settings. See Export Settings section below.
Sequence Nodes
Sequence Attributes: Opens a spreadsheet editor containing attributes for all available sequences.
Create Sequence Node: Creates a sequence node.
Scene Nodes
Embed Shape: Embeds the select object into the shape branch of the DTS hierarchy.
Renumber Selection...: Assigns a new trailing number to the name of the selected objects.
Register Details: Creates a detail marker using the detail number on the selected object and parents the detail marker under base01.
Bounding Box
Create Bounding Box: Creates a bounding box that fits the selected object(s). The bounding box is automatically triangulated and oriented with its local Z axis up.
Lock/Hide: Locks and hides the bounding box.
The menu bar in the dtUtility window has the following functions:
Setup submenu: Options for setting Maya's working units to work properly with Torque. See Setup section below.
Export..., Export Shape, Export Sequence, Export Settings...: Same as the buttons.
Export Shape and Dump: Exports the current scene as a DTS file and opens the dump file with the default text editor.
Export Sequence and Dump: Exports the current scene as a DSQ file and opens the dump file with the default text editor.
Embed Shape: Same at the button.
Detail Levels submenu:
Register Details: Same as button.
Create Detail Marker: Creates a generic detail marker and parents it to base01.
Renumber Selection...: Same as button.
Utility Nodes submenu:
Eye: Creates an eye node. Selection handle and local axis are visible for simple positioning and orienting.
Cam: Creates a cam node. Selection handle and local axis are visible for simple positioning and orienting.
Mount: Creates a mount node. Selection handle and local axis are visible for simple positioning and orienting
Sequences submenu:
Create Sequence Node: Same as button.
Add Trigger: Adds a trigger to the selected sequence node.
Delete Trigger: Delete a trigger from the selecte sequence node.
Sequence Attributes: Same as button.
Rendering Options submenu:
Visibility Animation: Enables visibility animation on the selected object.
Two-Sided Material: Enables two-sided materials on the selected object.
Delete Options: Deletes rendering options from the selected object.
Bounding Box submenu: Same as buttons.
More details regarding the specific functions of the buttons are presented throughout this document.
The Setup submenu in the dtsUtility window provides some options for quickly configuring Maya to work properly with Torque.
These menu items provide the same functionality as manually configuring the settings as outlined in the Configuration and Setup section above.
Set Linear to Meters: Sets Maya's linear working units to meters.
Set Time to 30 FPS: Sets Maya's time working units to 30 FPS (NTSC).
Resize Grid: Adjust the grid size to match the linear working units.
Reset Clipping Planes: Set the clipping planes of all cameras to .001 for nearClipping and 10000 for farClipping.
Set All Units: Applies all unit, grid, and camera adjustments.
Show Current Units: Displays current linear and time working units in a floating window.
By default, the Maya2DTS exporter will use the current scene file's name and the project's exportDTS and exportDSQ settings. Those settings can be overridden in the dtsUtility's Export Settings dialog box.
When first opened, the Export Settings dialog box will use the current file name for the shape and sequence names and the project's exportDTS and exportDSQ directories for the export locations. These settings may be customized as needed and are saved with the Maya scene file.
File names will automatically have the file extension appended to it.
Export locations are absolute paths. Relative paths will not work correctly. Also, the path must already exist prior to export. Otherwise, the exporter will not export the files correctly.
There is an option to use Global Settings for export. Global export directories are saved with Maya's preferences and can be used for multiple scene files. Shape and sequence settings are still scene-specific.
All Torque scenes must contain the following nodes at the scene root level in order to export properly: a bounding box named bounds and the DTS hierarchy.
The bounding box defines the shape's orientation and position in the world. Without the bounding box, the scene will not export.
The DTS hierarchy is a subtree of the scene that contains at least one detail level marker (an object whose name ends in a number) and at least one branch with children that have geometry somewhere in the sub-hierarchy and/or a joint hierarchy that deforms a mesh through a smooth skin bind.
A detail level marker indicates to the exporter what detail level mesh is to be drawn at a given distance. The number corresponds to the pixel size in the game engine at which the shape will be drawn.
The "branch" of the DTS hierarchy corresponds to the actual shape. The whole subtree can be under one branch, or there can be multiple branches. If you have one shape at the root level that you want to export (e.g. a static shape), the scene hierarchy should look like this:
The shape branch of the DTS hierarchy will look different if you are using a joint hierarchy (skeleton) to deform a mesh (e.g. a single mesh character). In this case, only the joint hierachy needs to be embedded in the shape branch, and the mesh (along with any detail levels) should be left at the scene root level. Here is what a sample character hierarchy might look like:
The structure of the graph will vary depending on the shape and the nodes that are needed for it export/function properly.
Each scene must contain a bounding box. If you fail to create a bounding box within your scene, the scene will not export. You must also name the bounding box bounds.
When you create the bounding box, you are creating a mini world that defines how the object will orient itself in the game. It is important to note that the orientation of the bounding box defines the orientation of the object. Positive Y is forward, and positive Z is up.
The bounding box should be a box that completely encloses the shape at all points in the animation. Make sure to scale up the bounding box so that the character does not break the edges of the box at any point during the animations. For example, if the character jumps up, you should scale the bounding box to make it taller so that the character always remains inside the bounding box.
After scaling the bounding box, you should apply a Freeze Transformations on the scale transforms. This will ensure that scaling information is not exported.
To freeze the scale transforms on the bounding box:
The scale transforms of the bounding box will now be set to 1 (or 100%) for all axes.
When you export your scene, the pivot point of the bounding box from Maya will become the pivot point of your shape in the exported scene. That is where all transformations will be calculated. That will also become the default mounting point for weapons, cameras, and other objects if the corresponding nodes exist.
It is important to note that Maya's default world space is Y-up while Torque is Z-up. The bounding box should be rotated -90 degrees on the X axis so that the Z axis is pointing up. To ensure that characters and objects created in Maya line up with Torque world space, they should be facing the same direction as the bounding box's local Y axis.
If you are using the Create Bounding Box button in the dtsUtility window, the bounding box will be correctly oriented for Torque. You should align the character with the bounding box as follows:
Ground animation (ground transform) is based on the animation of the bounding box. For example, if you want to export a running person, you would place the bounding box around the person at time 0, with the origin of the box at the persons feet. As the person runs, you would animate the bounding box to keep pace with the person.
The easiest way to do this would be to parent constrain the bounding box to the hips (or root) of the character, and set it to only constrain along the Maya world axis (not the bounding box axis) corresponding to the forward and backwards motion of the character.
Assuming that the character is oriented such that it is facing down the negative Z axis of the Maya scene, you can constrain the bounding box to an object as follows:
1. Select the root joint of the character.
2. Shift-select the bounding box.
3. Go to Constraint > Parent options box.
4. Uncheck everything except Translate Z.
5. Click the Apply button.
The bounding box will now move with the character whenever it moves forward or backwards, but it will not move up and down nor side to side. If you wanted the bounding box to inherit side to side motion (e.g. sidestep animations), then you would also constrain along Translate X in the parent contraint options box.
All shapes that are to be rendered in the engine must have a detail number at the end of the name. This number corresponds to the pixel height at which the shape will draw.
Each shape's detail number must have a corresponding detail marker that shares the same number. The base name for all the shapes must be the same, with the only difference being the detail number. Detail markers are named detail# where there is one marker for each unique detail number.
Only one of the detail meshes needs to be linked to the shape subtree. The other detail meshes should be left at the scene root level. At export time, these "loose" meshes are collected and added to the shape at the appropriate location. The transforms of these detail meshes are discarded and the transform of the corresponding shape in the subtree is used.
For example, if you have three detail meshes for a particular shape named shape2 , shape 64, and shape128, you must have three detail markers named detail2 , detail64, and detail128. Also, shape128 should be a child of start01, while shape2 and shape64 are at the scene root level. All of the detail markers should be parented to base01.
When the shape's size on screen is 128 pixels or greater, the shape with the detail number of 128 will be drawn. When the size is between 64 and 128, the shape with the detail number of 64 will be drawn. Likewise, when the shape's size is between 2 and 64, the shape with the detail number of 2 will be drawn.When the size is less than 2, nothing is drawn.
A detail marker in Maya is simply an empty group that is a child of base01. You can use the Register Details button to easily create detail markers based on the detail numbers of the selected mesh(es). You can also use create detail markers from DTS > Detail Levels > Create Detail Marker.
Below is an example of what the hierarchy for a shape with multiple detail levels might look like:
Configuration (.CFG) files are text files that allow you to specify how shapes and animations are exported. When you export a shape, the exporter looks for a file called <fileName>.cfg in the same directory as the Maya scene file being exported. The configuration file can contain several keywords that determine which object are exported and which objects are ignored as well as export parameter settings.
There are three lists that can be in the configuration file: AlwaysExport, NeverExport, and NeverAnimate. Node and object names are placed into one of those three lists. By default, all objects are implicitly placed into the AlwaysExport list. Names can include wildcards (*) to simplify writing configuration files. Lines with + or - along with the parameter name turn on and turn off boolean parameters. Lines with = set the value of valued parameters (note: the = occurs at the beginning of a line).
If a node's name matches a name on the NeverExport list, that node will not be exported. Any meshes that are children of that node will be parented to that node's parent (or its parent's parent if the parent is also on the NeverExport list). If a node is on the AlwaysExport list, it will be exported even if there are no meshes on the node, and even if the name matches a name on the NeverExport list. The AlwaysExport list takes priority over the NeverExport list. If a node is on the NeverAnimate list, its animation will not be exported even if it contains animations in Maya.
For example, assume that the following lines are in a configuration file:
AlwaysExport:
mesh*NeverExport:
submesh*
This configuration file would export all nodes that have names beginning with "mesh" and ignore all nodes beginning with "submesh".
An example configuration file with all parameter names are included in the File Pack.
There are two methods for exporting animation into the game. One method is to animate all of the sequences in one file and export it as a DTS file (as was done in the SimpleShapeTutorial). The other method is to separate each sequence into its own Maya scene file, export them as DSQ files, and then merge them together at runtime with a .CS file. having the base mesh and skeleton in one Maya file and having each sequence contained in its own Maya file is the preferred way to do this, because it give more explicit control of the nodes being exported and allows more control of the character. For simple shapes with only a few animations, putting all of the sequences in the main Maya file will work fine. For characters, it is recommended that you save each animation sequence in its own file and export the sequences as DSQs.
Sequence nodes tell the exporter how to export animation data over a given range of frames in Maya. They are required if animation is to be exported. The sequence node contains a variety of information such as the name of the animation sequence, start and end frames, cycling and blend information, and frame rate.
Sequence Nodes are actually just empty group objects with custom attributes and are placed at the scene root level. The naming convention for sequence nodes is Sequence_<name>. Sequence nodes must always be prefixed with Sequence_, otherwise they will not be exported. Sequence nodes can be created and edited manually, but it is easier to create them from the dtsUtility window.
To create a Sequence Node, click the Create Sequence Node button in the dtsUtility Window. The Sequence Attributes button opens a spreadsheet editor that allows you to edit attributes on all available sequences in the current Maya scene. The Sequence Attributes window only allows editing of attributes. Renaming must be done from either Outliner or the channel box.
startFrame: The first frame of the sequence.
endFrame: The last frame of the sequence.
cyclic: If turned on, the sequence will loop (e.g. walk and run animations). If turned off, the sequence will play once then stop (e.g. death animations).
blend: Makes the sequence a blend animation.
blendReferenceFrame: The reference frame number for the blend animation.
overrideDuration: The time scale for the sequence. Changing this attribute alters the speed and duration of the ground transform of the shape. The same keyframes will be used, but they will be played at different times. Default is -1.
frameRate: The frame rate for the sequence. Default is 30.
groundFrameRate: Frame rate for the ground transform. Default is 10.
priority: Controls what sequence will affect a node when two sequences want to control the same node.
ignoreGround: If turned on, the ground transform will not be exported for this sequence. Default is off.
Enable/Force Animations
Morph: This will force the exporter to export all mesh animations as a series of mesh snapshots. This is useful for certain types of animations (e.g. flags), but it will produce large files and does not contain animated nodes.
TVert: Enables animation of texture coordinates.
Visibility: Enables animation of the vis attribute.
Transform: Enables export of transform animation. Enabled by default.
Scale: Enables export of object scaling.
UniformScale: Enables export of uniform scaling.
AlignedScale: Enables export of aligned scaling.
ArbitraryScale: Enables export of arbitraty (non-uniform) scaling.
IFL: Enables export of image file lists (IFL). These are text files that list sequences of images files. Not supported at this time.
Triggers
The attributes for triggers will change depending on the number of triggers on the sequence node. See the section on Triggers for more information.
numTriggers: The number of triggers associated with the sequence.
triggerFrame#: The frame number on which the trigger occurs.
triggerState#: The state of the trigger.
To fully understand the animation system in the engine, one must realize that several animations (called threads in the engine) can be played concurrently, at different speeds in both directions, and can control different parts of the hierarchy. If two threads try to control the same node, the sequence priority will determine which thread controls a particular node.
In practice, the best way to go about doing things is to export different types of animation to control different parts of the character, and then have them hooked up to different controls. In the game, you can look around while running. Instead of having a run-look-left, run -look-middle, or run-look-right, there are individual run and look animations that are being played at the same time. In this way, you can get a great deal of flexibility out of very few animations.
The look animations are controlled by the mouse (running on one thread) while movement is controlled on another thread which is playing the lower body animations (forward, back, side). Celebration and death animations control the whole body and are played on the same thread as the body movement animations.
Viewing multiple threads is the ShowTool will be covered in greater detail in the ShowTool section.
By default, all transform animation in a shape during a sequence is exported. If a node differs from the default position in a sequence then the transform on that node is considered animated even if it is unchanging throughout the sequence. The default position for all nodes is determined by the node position at frame 0 in the Maya file. If Collapse Transforms is on, non-animating nodes will be collapsed out. If left unchecked, all nodes will be exported whether they animate or not, and as such, will be considered animating.
It is preferable to use .CFG files to determine which nodes are being exported to a particular thread, force export of needed nodes, manually cull out useless nodes (or ones with potential conflicts), and otherwise take steps to ensure that threads do not fight for control of the same nodes.
By using .CFG files, you can, for instance, animate and export animation for the lower body only and then other animation for the upper body only. When played in the ShowTool, the two threads will play without conflicts.
By explicitly culling out certain nodes, you can ensure that conflicts do not occur. Often the nodes that do not appear animated are indeed animating. This is especially true when using IK to animate, as the transform values of a node may be animating, but it might not be visible.
So, the ideal situation is to separate your animations into different types: full body, upper body only, lower body only, arms only, hands only, facial animation only, etc.
Create a separate directory for each animation type and make a custom .CFG for each type, culling out the un-needed nodes in the NeverExport list. Remember that the .CFG does not need to be named dtsScene.cfg. You can (and should) name them appropriately for the type of animations you are exporting.
Alternately, you can use Sequence Priority to determine which thread controls a node when conflicts occur, but this is a somewhat clunky way to deal with the situation. It is better to use the .CFG files to control the node structure of your .DSQ files to ensure there are no conflicts.
It should be noted that the base character mesh does not need to be present in the animation files that are to be exported as .DSQ files. The mesh information is not used in the sequence files. If you try to cull out certain nodes (ones that are being used in a smooth skin bind), the exporter will not let you. It thinks it needs the nodes to figure out the skin deformation properly. This is not a problem, as the mesh is not needed in the animation files (the deformation information is contained in the base DTS). The solution is to delete the mesh in the animation files.
It is a good idea for all of the shapes to be in or pass through a root pose that is the same in the DTS and all of the DSQ files. This will insure that all the animations line up properly. This can be as simple as making sure that the pose in frame 0 of all of the Maya files are exactly the same.
There are special sequences that can be marked as blend animations. These allow additive animation on the node structure of the shape. These will not conflict with other threads, and can be played on top of the node animation contained in other threads.
Blend animations are relative. Blends only read the changes that occur over the course of the animation and not the absolute position of the nodes. This means that if a node is transformed by a blend animation, it includes only the transform information for that node, and it will add that transformation on top of the existing position in the base shape (the DTS).
If a sequence is a blend, the transforms will be added on top of the other animations already playing in the engine on a node by node basis. Only the animation values are added.
Bear in mind that a blend can be played as a normal sequence, or it can be played on top of other sequences. When another sequence is playing, it will alter the root position, and the blend will be applied on top of that.
If you try to do a blend sequence where the root position is different than the 'normal' root (in the default root animation), you might expect that the blend will blend it to the new root (the position the character is positioned in during the blend animation). However, it does not work this way. Since nothing would actually be animating, it doesn't move the bones to the new position. What is contained in the blend sequence is only transform offsets from the blend sequence root position.
It is a good idea not to have a different root position in your 'normal' animations and your blends, as they can easily get out of sync.
You can determine the position that the blend animation uses for the animation offset by using the blend reference time.
The values added from the blend animation are based off of the root position in the DSQ file. This root position does not have to be the beginning of the animation. You can pick any position for the blend animation to reference.
This is useful, because you can have a blend animation that can have a reference position that is the 'root' position. For animation like hip twists and arm movements (as in the 'look' animation), the character can be in a natural default state. In this way, you can have one animation control the character through the base pose to an extreme in either direction while referencing the default 'base' state, which will exist somewhere in the middle of the blend animation.
You can set the blend reference postion either by entering the blend reference frame number in the appropriate sequence node or by leaving your character in the root position at frame 0 (the default reference position) and then animating the extreme positions after that in a sequnce that starts after frame 1.
Animation sequences that move the character must have ground transform. The engine knows that the character has a specific velocity in all directions (this is set in script). When the animations are being played, the engine is aware of what the distance covered is and plays the appropriate animation. If, for instance, the forward velocity of the character increases past the point of a walk animation to the speed of a run, it will transition to the run.
The exporter figures out the ground transform (meter per second over a given distance) by determining how much the bounding box has moved over the course of the animation in the Maya file. This is done automatically on export. You can allow the exporter to set the keys (frameRate), or you can set it to sample the distance covered explicitly by telling the sequence to use N frames and sample at the beginning and end of the animation (groundFrameRate). Use N frames is one by default and should be sufficient for most applications.
If you have no ground transform, the animation will not play when the character moves. In the Torque Game Engine with the default character, the forward ground transform is approximately 4 m/sec.
Triggers are arbitrary markers to can be used to call events on specific frames in a sequence. An example of a triggered event is calling footstep sounds and footprints during walk and run animations.
Triggers can be added to and removed from a sequence node by using the + Trigger and - Trigger buttons in the dtsUtility window. Each time you add or remove a trigger, the sequence's numTriggers value is automatically updated.
Because triggers are related to animations, their attributes are found in their respective sequences' attributes.
triggerFrame is the frame number on which a trigger event occurs.
triggerState is defines the state of a trigger. There can be up to 32 trigger states each with their respective on (1 to 32) and off (-1 to -32) values. What each of those trigger states means is up to you. You should work with your programmer to define what the trigger states mean and how you should work with them.
For example, you could have one trigger for each foot of a character that creates a footprint when the foot is down on the ground. Let's say that a triggerState of 1 is the left foot down and a triggerState of 2 is the right foot down. When the sequence plays the frame during which the left foot touches the ground, you could have a trigger on that frame that has a triggerState of 1 to create a footprint. You would then create another trigger with a triggerState of 2 for the right foot. You don't necessarily need to turn off the footprints (let's assume that the programmer will turn off when it is necessary), but you could by creating two more triggers with triggerStates -1 and -2.
There is one triggerFrame and triggerState per trigger. Trigger numbering starts at 0. For example, triggerFrame0 and triggerState0 are the first trigger, triggerFrame1 and triggerState1 are the second trigger, etc. Note that when you delete triggers from the list, all of the remaining triggers are renumbered starting from 0. Their frame and state attributes are retained.
Eye and cam nodes are required for getting your character working correctly in the default Torque engine. These are special nodes referenced in code that determine where the player point of view (POV) is and the rotation point for the orbiting death camera. The eye node is used for the first-person POV; the cam node is used for the third-person POV. Both nodes can be parented to the head of the character (or wherever is most appropriate).
These are not required for the character to export, but they are required in order for the character to be dropped in the game and work as a player correctly. If they are not included, the eye node will default to origin of the bounding box.
For weapons to mount correctly, the model must contain mount points. The weapon is mounted to mount0. Without it, the weapon will mount at the players bounding box origin.
Additional mount points may be added as needed. For example, the default player in the Torque Game Engine contains Mount0, Mount1, Ski1, and Ski2 nodes. Consult with your programmer to determine what is needed for your game.
Remember that all nodes (eye, cam, mount, etc) must be present in both the base shape (DTS) and all sequence files (DSQ).
To create eye, cam, and mount nodes, go to DTS > Utility Nodes and select the node that you wish to create.
What follows is a listing of the different types of animations that were used to create the default player character.
Normal Full Body
These animations are what you would consider to be 'normal' animations, with all the nodes exporting and controlling the entire skeleton.
Root
All Sitting
All Death Animations
All Celebrations
All Salutes
All Taunts
Lower Body Only
These animations are exported with a .CFG file that isolates the nodes in the lower body of the character.
Forward
Backward
Side (note: this is one animation played in reverse depending on direction)
Fall
Land
All Jumps
Blends
These animations are blend animations that are designed to be played on top of the movement animations and exist in the same directory as the full body animations (using the same .CFG) but are set to blend in the sequence node.
All Look
Head left/right
Head up/down
Recoil
Note that these seqeunces are animations that go from one extreme pose to another with the blend reference being the center position of the animation. The sequence is usually initialized to start in the middle and play either forward or backward from this state by the engine. The engine determines the position of the animation based on the user input (mouse look).
At runtime, the DTS and DSQ shapes are merged together to create a new shape that contains the mesh and all it's associated data (mountpoints, etc…) and the animations. This is done by including a .CS file for the shape in the directory with the DTS and DSQ file. The name of the .CS file for the shape should be the same as the DTS file. For example, player.dts has player.cs.
To construct a shape in engine, you start off with this at the beginning of the file:
datablock TSShapeConstructor(PlayerDTS)
This tells the engine the name of the shape it is constructing and is called in the engine.
After that, the shape and animations are added like this.
{
baseShape = "./player.DTS";
sequence0 = "./player_root.DSQ root";
sequence1 = "./player_forward.DSQ run";
sequence2 = "./player_back.DSQ back";
sequence3 = "./player_side.DSQ side";
sequence4 = "./player_lookde.DSQ look";
sequence5 = "./player_head.DSQ head";
sequence6 = "./player_fall.DSQ fall";
sequence7 = "./player_land.DSQ land";
sequence8 = "./player_jump. jump";
};
The base shape is added, and then all the sequences are added to the shape and given a number. All of the numbered sequences reference a file. Names can be associated with the animations. You can see these names in the ShowTool in 'thread' control. For example, Sequence 0 is created in the shape, it uses player_root.DSQ, and the name of the sequence is root.
When you create a .CS file for your shape, it is important that the sequences are entered into the list in the correct order. Animations are called by the engine by index number, not by name. Consult with your programmer about the numbering scheme you wish to implement to call the animations.
The ShowTool is simply a compiled Torque application that is running without game information and with a very simple UI. It is used to load and preview shapes and animations that have been exported using the Maya2DTS exporter (or any other exporter supported by Torque).
In order to view shapes in the ShowTool, the shape and texture files must reside in a directory inside the Torque project. If you are using the demo, you can place the files in demo\data\shapes inside the Torque example directory.
The ShowTool can be accessed by putting the argument -show when you launch the application. This can be done from the command line, but it is easier to just add the switch into a shortcut.
After launching the ShowTool, you will see a black screen with several buttons on the left-hand side.
To load a shape into the ShowTool, click the Load Shape button, select a shape from the list, then click the Load button.
Your shape will appear in the middle of the window. You can navigate around the shape by using the W, S, A, D, E, C, X, and Z keys.
W: zoom in
S: zoom out
A: rotate left
D: rotate right
E: rotate camera up
C: rotate camera down
Z: rotate camera left
X: rotate camera right
To manually view detail levels in the ShowTool, click the Detail Control button to open the Detail Control window.
By default the detail control will be set to Slider Sets Detail Level. Drag the slider to display the different detail levels.
Click the arrow button to switch to Auto Detail Using Distance. As you zoom in and out, you will see the different details levels change as the object gets closer to and further from the camera.
Other useful information is contained in the panel, including which detail level is being displayed and the polygon count.
You can manually load animations onto shapes by clicking the Load Sequence button. As long as the animation sequence matches the shape, then the shape will animate correctly
If the shape already has animations and is using a .CS file to merge DTS and DSQ files, then the animations are automatically loaded into a thread.
To view animation threads, click the Thread Control button to open the Thread Control window.
The Thread Control window allows you to playback and test all of the animations in your shape. The sequences list displays each animation for your shape using the name and order that was designated in the .CS file.
You can view all of the shape's animations by clicking through the list of sequences.
You can also add another thread by clicking the New Thread button. This will give you a second thread that can run another animation simultaneously to the animation running in the first thread. Normally, multiple animation threads can be created for different parts of the body. You can have one thread controlling the lower body, a second thread for arms, a third for the head, etc. Multiple full body threads are not normally used and can behave unusually.
The threads can be controlled individually, started and stopped individually, played at different speeds (using the Edit Scale button), and transitioned individually on a thread by thread basis. In code, animations can be controlled to respond to the player input, play in reverse, play at different speeds based on player input, and transitioned at different speeds and over varied lengths of time, again, on a thread by thread basis.
Although you cannot explicitly export or set transition parameters from Maya, the engine supports transitions. Transitions will transition from one sequence to another on a node by node basis over a set period of time (which can be varied). The transition is linear.
Using transitions allows the artist to animate without hitting the root position accurately. The engine will transition from one sequence to the other. This also allows for the engine to transition from one sequence to another mid-sequence (not returning to the root position). In this way, a character can go from a run to a walk mid-sequence (e.g. the character does not need to complete the animation) and the engine will interpolate the node positions during the change. Note that this can introduce some strange behaviors, because the engine will take the shortest path to translate the nodes to the next state.
To test how one sequence transitions into another, open the Thread Control window then click the Transition button to bring up the Transition Control window.
In the Window, the first arrow button will be set to Set Sequence. This means that the transition will pop to each new animation as you click through the list in the Thread Control window. Click the button to change the setting to Transition to Sequence. The sequences will now transition from one sequence to the next as you select them in the thread control window.
The other two arrow buttons allow you to play with how the transition happens. By default, the second button is set to Transition to Synched Position. This transition between the sequences using a default value. You can press this button to change the mode to Transition to Slider Position, which allows you to use the slider to determine where on the target sequence you want the transition to go to.
The last arrow button allows you to have the target sequence either play or pause during the transition. This is rarely used and usually works better if the target sequence is playing during the transition.
The Edit Duration button allows you to change how much the transition takes to go from one animation to another.
There is no correct way to make collision objects for the Torque engine. It all depends on how your programmer wants to implement collision detection. Several games used this engine and they all used different collision schemes. Different collision schemes can be different for different shapes as well. Some shapes use simple sphere collision that is derived from the bounding box, some have custom-built collision shapes. Vehicles tend to have custom collision shapes.
Custom collision shapes can be created by assigning a negative detail number to the shape and creating a corresponding detail marker. Shapes with negative numbers will export but not draw. Because Maya does not allow dashes ("-") in object names, underscores ("_") must be used.
The Torque Game Engine presently uses detail markers named Collision_# with the mesh shapes named Col_#. The shapes must be convex hulls (no concave surfaces). Collision markers must be children of base01 (same level as detail markers). Collision meshes should be in the shape subtree.
Here are some of the naming conventions:
Collision_1 through Collision_9: These are collision markers.
Col_1 through Col_9: These are the actual collision meshes.
LOS_9 through LOS_15: Markers for line of sight, or "bullet", collision shapes.
LOScol_9 through LOScol_15: Geometry for line of sight collision.
Keep the detail meshes as low in polygon count as possible, because collision can be processor intensive. Vehicles are limited to ONE collision mesh for the collision shape
This section covers setup of vehicles for use with the Torque Game Engine. The vehicle physics and collision shapes are pretty touchy. They work, but they require a great deal fine tuning to get them to work properly.
This entire section is a list of what is contained in the shapes and the functionality and naming conventions for these types of shapes.
Ground: Each wheel needs a ground node, i.e. Ground0, Ground1, etc. These tells the wheels where they touch the ground.
Mass: Each vehicle needs a mass node. This should be positioned at the center of mass for the whole shape. This is used in the driving and flying dynamics.
Eye: Each vehicle needs an eye node. This is where the camera will be placed when the player is piloting a vehicle in 1st-person mode.
Mount: Each vehicle needs mount nodes. These are where the players and weapons mount. Here are the names of the mount nodes and their function:
mount0 – pilot
mount1 – navigator\gunner
mount2 – passenger
mount3 – passenger
etc..
mount10 – gun
mount9 – bomb mount point on the bomber vehicle
Turn: Each wheel needs a turn sequence, ie. Turn0, Turn1, etc. This controls the steering.
Spring: Each wheel needs a spring sequence, ie. Spring0, Spring1, etc. This controls the up/down motion of the wheel (like shocks)
Wheel: Each wheel needs a wheel sequence, ie. Wheel0, Wheel1, etc. This controls the spinning of the wheel.
Collision_1: The marker for the collision detail level. Detail levels -1 thru -8 are reserved for regular collision objects. Vehicles use only ONE shape (-1), because vehicle dynamics are processor intensive.
Col_1: This is the actual collision geometry for the vehicle itself. It should be as absolutely LOW POLY as possible. Every polygon counts, and the game will slow down if you have too many. Also, pay special attention to the way the collision geometry is shaped to minimize collision with small bumps/hills/slopes etc. Changing this shape will dramatically effect whether or not the vehicle is prone to getting stuck while driving over bumps.
LOS_9 thru LOS_15: Markers for line of sight collision (e.g. bullet collision).
LOScol_9 thru LOScol_15: Collision geometry for line of sight collision tests.
Smoke_node0,1,2,etc: These are smoke emitters for when the vehicle is damaged.
Contrail0,1,2,etc: These are nodes for emitting contrail particles for flying vehicles.
More to come...
