Torque Game Engine DocumentationVersion 1.3.x
| Torque Game Engine Documentation Version 1.3.x |
This document will take you through the steps of setting up some simple shapes that will familiarize you with the exporter and how it works, later we will move on to more complex topics.
Be sure to read later chapters before attempting more complex forms, as this chapter does not cover many important features and limitations of the exporter.
In this section we will be creating a simple sphere shape in 3D Studio Max. You can use the SimpleShape.max in the file pack to follow along with.
Procedure 8.1. Create a Simple Sphere
From either the top, user, or perspective view, create a sphere with 16 sides.
Creating the shape from the Top, User, or Perspective view ensures that its axis is aligned properly. This will be very important when the shape exports.
Make sure the sphere has mapping coordinates by putting a check in the checkbox at the bottom of the creation panel.
Meshes without texture mapping coordinates will not work correctly in the game. Make sure you have UV coordinates on the meshes you are trying to export.
Align the sphere to the center of the world using the transform type-in floater. (While in Move Mode, go to Tools. Transform Type-In) and enter 0 in all the boxes in "Absolute World".
Name this shape "SimpleShape".
Procedure 8.2. Texturing the Sphere
Copy SimpleTexture.bmp from the file pack and put it in your export destination directory in the Torque project. The texture must reside in the same directory as the exported file in order to work in the show tool and the game.
Go to the 3D Studio Max Material Editor and select a material. Open the 'maps' rollout panel. In the diffuse slot, select the button to choose a texture. Select 'bitmap' from the list. Find and choose SimpleTexture.bmp.
Turn on 'Show map in Viewport' (the button looks like a little checkerboard cube.)
You are now ready to prepare your shape for export.
Procedure 8.3. Create the Bounding Box
Make a box that encloses the entire shape. Again, do this from either the top, user or perspective view.
Align this to the world center as above.
Name this box "bounds".
Procedure 8.4. Add The Detail Number
Select SimpleShape.
Press the "Renumber Selection" Button. A dialog box will pop up.
Enter '2' in the window and hit OK. This will add a trailing number to your shape (this will be the detail resolution).
It does not refresh the Max interface, so deselect SimpleShape and select it again in order to see the changes.
Make sure SimpleShape (now named SimpleShape2) is selected, and press Embed Shape button. Open the schematic view. The hierarchy should look like that shown in Figure 1.
Figure 1
The Embed Shape button correctly created a hierarchy for your shape which will allow it to export. It did this by creating a few dummy objects and then naming them correctly. This can be done manually as well, using MAX dummy objects for the base and start shapes and the detail markers.
You are now ready to export the shape.
Procedure 8.5. Exporting
Go to the Utility panel, choose the 'DTS Exporter Utility'
Export the shape by choosing Export>Whole Shape.
Export this shape to your destination directory in the Torque engine. Name the shape SimpleShape.DTS
Make sure your texture map is in the same directory as the DTS shape. If it is not, the texture will not load and the shape will show up white.
Try loading SimpleShape.DTS in the Show Tool and looking at it.
Here we will be creating lower resolution versions of the Simple Shape that will replace it when it is distant from the camera. This helps reduce the number of polygons on the screen. If done carefully, levels of detail will be completely invisible to the user. The object will be swapped to a lower poly version at such a distance that the details that are lost are too small to be seen. Which detail level is used is determined by the pixel height of the object on screen. This prevents users with high resolution setting from noticing the reduction of detail, and mean that there will be fewer polys onscreen for users with lower resolutions (as they are likely on slower hardware).
Procedure 8.6. Create the Detail Objects
Here we will be creating lower resolution versions of the Simple Shape that will replace it when it is distant from the camera.
Select SimpleShape2.
Rename the shape to SimpleShape 128.
Clone the shape by using Edit>Clone (make sure it is a copy and not a reference or an instance).
Rename this new shape SimpleShape 64 The clone should be selected. In the modifier panel, turn the 'segement' down to 8. This means that when the object is between 64 and 128 pixels high (above its detail number, but below the next highest), it will display a sphere with 8 segments.
Repeat this process a second time, this time naming it SimpleShape2, and turning the segments down to 4. This means that when the object is between 2 and 64 pixels high, it will display a sphere with only 4 segments.
Unlink SimpleShape64 and SimpleShape2 from Start01.
Select Base01, and press the "register details" button on the DTS exporter panel. It will automatically create your detail markers.
You can now export this as a DTS, overwriting the old SimpleShape.DTS
Examine the effect of you levels of detail in the Show Tool.
The MultiRes modifier in 3DSMAX is supported for detail level creation. Continuous level of detail is not supported. At export time, the exporter looks to see if there is a MultiRes modifier on the object and if so, creates static Level of Detail meshes based on the parameters input into either the shapes "User Properties" or through the .CFG file using the T2Autodetail parameter.
Procedure 8.7. Simple Shape Detail Levels using MutliRes
Open SimpleShape2.max located in the documentation file pack.
Now, install this macroscript named adjustLODs.mcr, also found in the file pack.
Many thanks to Jon Lanz for writing this very useful utility. Please refer to your 3DSMAX help file about how to install macroscripts.
Now, launch the script by pressing the AdjustLODs button in your toolbar. Select the MultiRes shape, and you should see something similar to Figure 2.
Figure 2
Since the detail meshes do not actually exist in the scene, the 'Register Details' utility will not pick them up. You will have to construct the detail markers manually.
If you have anything in the user properties, the script will choke on it. Cut and paste any text in the user properties somewhere else.
The buttons that signify the detail markers will be un-pressed, press them, as shown in Figure 3. This will enable the script to write the necessary data for the Multires export into the user properties (thus saving you some time and effort of doing this yourself).
Figure 3
The "spinners" that you see next to the detail markers are what is used in the script to generate the user properties information for the Multires detail settings that you have enabled. Spinner changes are not interactive, so you won't see any changes occur as you move the numbers around. In order to see how each detail level will effect your model, adjust the percentages in the MultiRes mesh. When you see something you like (or you hit your target polygon count for a certain LOD), adjust the spinner in the script to match, as shown in Figure 4.
Figure 4
The numbers in the Adjust LODs script are in decimal percentages, while the MultiRes modifier uses an actual percentage. You will have to convert the 0-100% values you see in MultiRes to 0.0-1.0 when entering them into the script.
You will almost always want your highest level of detail to use the 100% of the original models complexity (otherwise, why make is so detailed to begin with?). Because of this, you will want to set the top spinner to 1.0.
When you are happy with the settings, click "apply settings", as shown in Figure 5.
Figure 5
Open up the user properties of your object, you will observe that the syntax that was outlined in the "MultiRes and Detail Levels" section, has been placed here by the script, as shown in Figure 6. The values can be entered by hand if necessary, the script just makes it easier.
Figure 6
Make sure you turn the dial in the MultiRes modifier back up to 100% before exporting.
The shape should be ready to export. Export it and test out you levels of detail in the Show Tool.
There is no "right" way to make collision objects for the Torque engine. It all depends on how your programmer wants to implement collision detection. Every game has a different set of requirements when it comes to collision, depending on the gameplay style and need to balance precision with performance. 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, trees, and other objects that are larger than a character tend to have custom collision shapes.
Custom collision shapes can be created by assigning a negative detail number to the shape (like -1) and creating a corresponding detail marker. Shapes with negative number will export but not draw.
By default, the Torque engine uses detail markers named "Collision-n". These markers are dimply dummy objects, like those used to mark levels of detail. Also like LOD, each collision marker must have a corresponding mesh object. These mesh shapes are named Col-n. The number (n) must be between -1 and -9, and .
The collision shapes must be convex hulls (no concave surfaces). You want your collision mesh to be a close fit, not a precise representation of your model. Keep the detail meshes as low in polygon count as possible as this is very processor intensive.
Here are some of the naming conventions.
Collision-1 thru Collision-8: These are the collision markers.
Col-1 thru Col-8: These are the actual collision shape geometry. They should be linked into the hierarchy under the start node.
LOS-9 thru LOS-16: Markers for line of sight, or 'bullet' collision shapes.
LOScol-9 thru LOScol-16: Geometry for line of sight collision. They should be linked into the hierarchy under the start node.
Vehicles are limited to ONE collision mesh for the collision shape.
Procedure 8.8. Creating Collision Details for Simple Shape
Open SimpleShape3.max located in the documentation file pack.
Clone one of the detail markers and name it "Collision-1"
You could also create the collision marker by adding a new dummy object to the scene and naming it "Collision-1", then linking it to "base01".
Make a copy Clone of SimpleShape 128 and change the segments to 6. Name this mesh'Col-1'.
Cloning is not a good method for creating collision meshes in most cases. We only do it here because SimpleShape is so simple to begin with. For more complex shapes such as vehicles and characters, it is very important that you build simplified collision meshes by hand. Cloning will not work on anything more complex than a cube or sphere.
Export this shape. It will now have a collision mesh. The easiest way to test this is to replace an existing shape in the demo with it. You can export simpleshape.dts over bush1.dts. Make sure you rename the old bush and have your texture in the correct directory. In the demo your character should now collide with your shape rather than passing through it.
The following describes procedures and usage for texture mapping of objects in the Torque engine.
General Texturing Information
Material Colors and procedural textures are not supported.
Only bitmap textures are supported.
Multi sub-object maps are supported, as long as all the subobjects are bitmap textures.
Textures maps must be powers of two (32, 64, 128, 256, 512). The maximum size supported is 512X512. Textures do not have to be square.
Bitmaps formats supported are .PNG .JPG
All surfaces must have UV coordinates for their textures to display correctly.
Translucent textures are supported. To make an object translucent, the texture on the object must have an alpha channel. The amount of translucency is controlled by the alpha channel. Put the texture in the diffuse mapping slot and check the 'Opacity' checkbox in the material editor. You don't need to put a texture in the Opacity slot, it will get the opacity information from the alpha channel.
Double Sided Materials are supported are supported. You can make a material 2-sided by going into the material editor and turning "2-sided" on. This feature is disabled by default and is turned on in the DTS exporter utility parameter rollout panel.
Open the file SimpleShape4.max and load the associated texture SimpleTexture4.png in the material editor. These files are located in the documentation file pack. The texture map is shown in Figure 7.
Figure 7
You will see that the material applied to the shape is a translucent .png. In the material editor, check the "2-sided" option.
Making this material double sided is important because you will be seeing the inside of the object through the translucent sections of the texture map. On most objects, double sided textures are a bad idea because they will double the number of surfaces rendered, yet never be visible to the user.
In the DTS Exporter settings in the utility panel, make sure 'Enable 2-sided materials' is checked in the Parameters rollout. This tells the exporter to expect double sided textures. If this is not checked, the exporter will ignore the double sided texture and export it as normal.
Export the shape. Checking Translucency in the ShowTool. You will see something resembling Figure 8.
Figure 8
You will note, that the shape is all screwed up. Things are not drawing in the correct order. Some of the polygons are drawing in front of other polygons. This is due to the way translucent shapes are drawn in the engine. More details on why this happens is covered in Appendix ????. In order for translucent shapes to draw correctly they must be forced to sort in the correct order. The next section will discuss how this is done.
It is important that transparency sorting only be used on simple shapes. SORT:: subdivides the polygons of the shape in order to correctly display their transparency, but the complexity of the shape created increases geometrically with the number of polygons sorted. The technical details of transparency sorting are covered in detail in Appendix ????.
Procedure 8.10. Setting up the SORT:: function
Select the SimpleShape and prepend the name of the object with "SORT::". It should now be named "SORT::SimpleBox2" This will tell the exporter that this object may have trouble sorting and it will take extra steps to ensure it sorts correctly.
Re-export the shape and open it in the ShowTool. It now sorts correctly, as shown in figure 9. The exporter has split some of the faces so that it the rendering engine can tell which faces are in front more easily. This increases the polygon count of the shape (you can check this in the detail level window in the showtool).
Figure 9
To make an object environmentally map, check the "Reflection" channel in the material editor. You do not need to put a texture in the slot. You can control the amount of reflectivity by adjusting the spinner. If there is an alpha channel contained within the texture in the diffuse slot, the alpha values will be used to determine the amount of reflectivity. If there is no alpha channel, then the object will appear to be uniformly reflective based on the spinner value (100% will make the object chrome).
Make sure that environment mapping is on in the engine. You can do this by making sure that $pref::environmentMaps = "1" in your prefs.CS and clientprefs.CS files.
Environment mapping will not work in the ShowTool. Changes to the directory structure removed this feature from the showtool. Check your environment mapping in the game.
If you want a translucent texture to environment map, mark the "reflection channel" in the material editor and the "opacity" channel.
The alpha channel present in the diffuse map will be used to determine opacity. The spinner value in the reflection channel is used to determine the amount of reflectivity.
Sequence objects are necessary if animation is to be exported. The sequence object tells the exporter how to export animation data over a given range of time in 3D Studio Max, and what to call the sequence. A sequence object can be created like any other helper object found within 3D Studio Max. In the Create tab, select the "Helpers" menu. Use the pull down menu to choose "General DTS Objects". See the section on the Sequence Object Parameters ???? for more details about the sequence objects.
Figure 10
Sequence helpers that you place in the scene are unlinked objects that float unlinked in the world. They do not need to be linked to anything.
Sequence Helpers are used to define the beginning and end of an animated sequence. You can set these parameters by adding keyframes to the Sequence Begin/End track. This track is an on/off type track. The animation information will export only when its value is set to on.
Figure ?
By default, the first key you add will define the beginning of the animation, and the second will determine the end.
Figure ?
In the next section, we will be adding an animation sequence to our simple shape.
Procedure 8.11. Adding Sequence Objects to an Animated Shape
Open SimpleShape5.max located in the documentation file pack.
The shape has been animated. Only the highest level of detail is animated, and the lower detail levels are not. This is true of any animated objects, as the lower levels of detail are simply swapped for the highest, and will use its transforms when exported.
Create a sequence helper. Name it SimpleAnimation.
Open the trackview and find the Track for SimpleAnimation. Using the create key button, add a keyframe at frame 0 in the Sequence Begin/End track. Put another one at frame 40. This establishes the begin and end points for the sequence.
That is all that needs to be done. Export the shape and open it in the ShowTool. It will be animating when you open it. Use the detail slider to go through the detail levels and notice that all the detail levels are using the animation form the main detail level. The transforms of the lower detail levels have been discarded and they are instead using the transform from the highest detail level.
The Torque Game Engine support animated visibility.
Visibility is controlled by an object's visibility track. A visibility track of an object can be created in the Track View (consult your 3D Studio Max documentation if you do not know how to do this).
If the value of the visibility property is 1 the item is visible, if it is 0 or less the item is not visible. This much is the same as before. But now as the value goes from 0 to 1 the shape will fade in.
If you don't want the object to fade in but to go from visible to invisible all at once, then make sure visibility goes from 0 to 1 between one frame and the next.
Visibility animation must be checked in the Export control parameters rollout.
Procedure 8.12. Simple Shape with Visibility Animation
Open SimpleShape6.max located in the documentation file pack.
Select the object and open the track view. Notice that it has a visibility track and that the track is animated. A value of 1.0 makes the object fully visible, and a value of 0.0 makes the object fully invisible (intermediate values are allowed. A value of .5 will make the object 50% transparent.)
Make sure 'Visibility Animation ' is checked in the Sequence 'export control' rollout and export the shape. When you check it in the ShowTool, you will notice that just like transform animation, the lower detail levels have acquired the visibility animation.