Torque 3D¶

Adding A DTS Model¶

Before you can add a DTS model to World Builder so that it can be placed in a game level, it must be created with an appropriate application. It must then be placed in a folder where the World Builder can find it. When the World Editor is started it searches the game directories for objects and automatically loads any that it finds into the appropriate sub-tabs of the Library based upon the folders they were found in. Placing a model into the /game/core/art/shapes folder of your game project, or any sub-folder that you create, will allow the World Builder to find it and list it in the Library on start-up.

If you’ve added files or folders after starting World Builder those new entries will not appear until you have navigated out of a folder, or parent folder, and back in again.

Once a model is listed in the Library it is ready to be added to your game level. To add a model to your game level, select the Object Editor tool. Click the Library tab in the Scene Tree panel. Finally, select the Meshes sub-tab. Once the Meshes tab is open, select the entry from the drop down list. This list represents the directory containing your .dts model.

Click on the entry that contains your DTS model name. Hovering over the entry will display information about the model. Double-click the shape to automatically add it to your scene. The file should load extremely fast but you may not be able to see it right away. Where an object is placed in the scene depends upon the current drop location selection which can be set the menus Object > Drop Location command. Move your camera from its current location until the shape is in view.

Adding A COLLADA Model¶

Torque 3D also has the ability to load and render COLLADA models (.dae) . The process of adding a COLLADA shape is identical to adding a DTS. You will first need to create the COLLADA file and place it where the World Editor can find it then you may place it in a level.

Open the Library > Meshes tab. Navigate to the directory containing your COLLADA model (.dae). If you hover over the item, you will get a brief file description.

Double clicking an object will open the COLLADA import dialog. For the purpose of this example, you can just click OK to load the mesh.

The file should load extremely fast, but you may not be able to see it right away. Where an object is placed in the scene depends upon the current drop location selection which can be set the menus Object > Drop Location command. Pull your camera up and away from its current location until the shape is in view.

Shape Properties¶

Each shape in a scene has properties which can be set like any other object using the Object Editor. Clicking a shape in the scene or selecting it from the Scene Tree will update the Inspector pane with information about that object. Shapes have their own unique set of properties.

Creating Blank Terrain¶

To create a new blank terrain start from the menu by selecting File>Create Blank Terrain.

After you click the menu entry, a Create New Terrain Dialog will appear.

The Name field allows you to specify a name for your Terrain Block. This name will appear in the Scene Tree and can be used to reselect your terrain later for editing. Enter a name for the terrain in the text box, in this example theterrain.

The Material for the terrain, that is the texture that will be displayed to depict the ground cover, is selected using a drop-down list. This list is populated by the World builder with all the existing materials created specifically for terrains.

The Resolution that you select from that drop-down list determines the size of the terrain that will be created. The size of the terrain that you choose is largely dependent on the design of your game. You will have to experiment to find the right size that works for each game you create and some combinations of options are not very practical. For example, selecting a terrain size of 256 and using the Noise option will result in a terrain that is so drastically contoured that it will not be of much use.

The radio buttons to the right of the Resolution dropdown determine the smoothness of the terrain that is generated. Selecting Flat will create a relatively smooth terrain and selecting Noise will generate a bumpy terrain.

Creating a Flat Terrain¶

To create a flat terrain: from the main menu select File > Create Blank Terrain; enter a name; select a material; select a size such as 256; and select the Noise radio button, then click the Create New button. A contoured Terrain Block will be generated and automatically loaded into the scene.

A Flat terrain is a great place to start, but is more suitable for terrains that will remain relatively flat. Using a flat terrain requires you to create all the terrain details yourself using the Terrain Editor.

Creating a Bumpy Terrain¶

To create a bumpy terrain: from the main menu select File>Create Blank Terrain; enter a name; select a material; select a larger size such as 1024; and select the Noise radio button, then click the Create New button.

Terrain Block loaded into the scene. A contoured extremely mountainous terrain will be generated and automatically loaded into your scene. The noise algorithm randomly generated the hills and valleys for you.

Starting with a contoured terrain this is a decent method of starting from scratch with a little randomness thrown in.

Adding an Existing Terrain File¶

To add an existing terrain file to a level start by selecting the Object Editor tool. Locate your Library panel and click it. Click on the Level tab then select the Environment folder. Once that is open, locate the Terrain Block entry, and double-click it.

The new terrain dialog will open.

The Object Name field allows you to specify a name for your Terrain Block. This name will appear in the Scene Tree and can be used to reselect your terrain later for editing. Enter a name for the terrain in the text box, in this example theterrain.

The Terrain file box indicates the information file which holds the data describing the terrain to be loaded. Clicking the box loads the OS file browser.

Terrain files are named with a .ter extension. The .ter file type is a proprietary format that contains terrain data understood by Torque 3D. Locating a .ter file then clicking Open/OK will cause it to be selected as the Terrain file to be loaded.

Leave the square size in the dialog set to its default value then click OK. The .ter file will be immediately imported into your scene with both geometry and textures. The sample shown here is a very simple and low detailed terrain file.

Importing a Terrain¶

The most recommended and effective method to add a Terrain Block to a level is to import the terrain from external data files. However, this method requires the skill and the third-party tools to create those data files. Very high-quality and professional-looking terrain can be created with tools such as L3DT and GeoControl. These tools allow you to generate extremely detailed heightmaps that can be imported by Torque 3D and to generate terrain data.

There are several types of asset required to import and use a terrain in Torque 3D using this method:

• a heightmap
• an opacity map and layers
• texture files.

Heightmaps¶

The primary asset required is a heightmap. A heightmap is a standard image file which is used to store elevation data rather than a visible picture. This elevation data is then rendered in 3D by the Torque engine to depict the terrain. The heightmap itself needs to be in a 16-bit greyscale image format, the size of which is a power of two, and must be square. The lighter an area of a heightmap is, the higher the elevation will be in that terrain location.

Example Heightmap

Opacity Maps¶

An opacity map acts as a mask, which is designed to assign opacity layers. Opacity layers need to match the dimensions of the heightmap. For example, a 512x512 heightmap can only use a 512x512 opacity map.

If the opacity map is a RGBA image, four opacity layers will be used for the detailing (one for each channel). If you use an 8-bit greyscale image, only a single channel. You can then assign materials to the layers. This allows us to have up to 255 layers with a single ID texture map, saving memory which we can apply to more painting resolution.

Notice that the following example Opacity Map resembles the original heightmap.

Example Opacity Map

Texture Files¶

Texture files “paint” the terrain giving it the appearance of real ground materials. When creating a terrain from scratch textures can be manually applied to it using the Terrain Painter, which is built into the World Editor, but that is a time and effort intensive method. Instead of hand painting them, the opacity layer will automatically assign textures to the terrain based upon what channel they are loaded into.

For each type of terrain to be rendered you will want to have three textures: (1) a base texture, also referred to as a diffuse texture, (2) a normal map, and (3) a detail mask.

Diffuse

Normal

Detail

The base represents the color and flat detail of the texture. The normal map is used to render the bumpiness or depth of the texture, even though the image itself is physically flat. Finally, the detail map provides up-close detail, but it absorbs most of the colors of the base map.

Importing a Heightmap¶

To import a heightmap for terrain start the World Editor, then from the menu select File > Import Terrain Heightmap:

The Import Terrain heightmap dialog will appear.

Name

If you specify the name of an existing Terrain Block in the dialog it will update that existing Terrain Block and its associated .ter file. Otherwise, a new Terrain Block will be created.

Meters Per Pixel

What was the Terrain Block SquareSize (meters per pixel of the heightmap), which is a floating point value. It does not require power of 2 values.

Height Scale

The height in meters that you want pure white areas of the heightmap to present.

Height Map Image

File path and name of a .png or .bmp file which is the heightmap itself. Remember, this needs to be a 16-bit greyscale image, the size of which is a power of two, and it must be square.

Texture Map

This list specifies the opacity layers, which need to match the dimensions of the heightmap image. If you add an RGBA image it will add 4 opacity layers to the list, one for each channel. If you add an 8-bit greyscale image, it will be added as a single channel.You can then assign materials to the layers. If you do not add any layers or do not add materials to the layers, the terrain will be created with just the Warning Material texture.

Click the browse button to the right of the Height Map Image box to open a file browser dialog. Navigate to where your terrain files are located, select the desired heightmap PNG file, then click Open. The selected heightmap file will be entered in the Height Map Image box.

Click on the + button next to Texture Map to open another file browser. This is where you add opacity layers. Start by locating the masks. If you have the right assets, it should resemble something like this:

Do not worry if you do not see the detail. The mask is supposed to be solid white. Repeat the process until you have imported all your opacity layers.

Now that our opacity layers have been added, you should assign a material to each one. You can do so by clicking on one of the layers, then clicking the edit button in the bottom right. You will now see the Terrain Materials Editor.

Click the New button, found at the top next to the garbage bin, to add a new material. Type in a name then click the Edit button next to the Diffuse preview box. Again, a file browser will pop up allowing you to open the base texture file for the material. Alternatively, you can click the preview box itself, which is a checkerboard image until you add a texture.

Once you have added the base texture, the preview box will update to show you what you opened. Set the Diffuse size which controls the physical size in meters of the base texture.

Click on the Edit button next to the Detail Preview box. Using the file browser, load the detail map.

Next, click on the Edit button next to the Normal Preview box. Use the file browser to open the normal map.

Your final material properties should look like the following:

Repeat this process until each opacity layer has a material assigned to it. Back in the Import Terrain Height Map dialog, click on the import button. It will take a few moments for Torque 3D to generate the terrain data from our various assets. When the import process is complete, the new Terrain Block will be added to your scene (you might need to move your camera back to see it).

If you zoom in close to where materials overlap, you can notice the high quality detail and smooth blending that occurs.

Terrain Block Properties¶

A Terrain Block has properties which can be set like any other object using the Object Editor. Clicking a Terrain Block in the scene or selecting it from the Scene Tree will update the Inspector pane with information about it. Terrain Blocks have their own unique set of properties.

Adding Ground Cover¶

To add a ground Cover object to a level, select the Library tab in the Scene Tree panel. Click on the Level tab and double-click the Environment folder. Locate the Ground Cover entry.

Double-click the Ground Cover entry. The Create Object dialog will appear.

If you already have a material or shape you want to use, you can set them here. Materials are used to paint the ground with textures which can contain transparency so that the underlying ground shows through. A Shape File is used to replicate 3D objects on the ground. Enter a name for you Ground Cover object then click the Create New button. A new Ground Cover object will be added to your level. Without a material, the system will render a pattern on the ground with the default “No Material” texture:

To change the No Material indicators to a real Material scroll through the Ground Cover properties until you get to the Ground Cover General section. In the Material field, click on the globe to open the Material Selector:

Material Field

When the Material Selector appears, you have the option to pick an existing material or create a new one in the Material Editor.

Assigning Terrain Material¶

When you first add a Ground Cover object, it will place the material or shape on the entire terrain. To limit the placement of Ground Cover, you must set the terrain layer. To set the terrain layer with the Ground Cover selected, scroll down to the Ground Cover General set of fields. Find the Types sub-section.

Types is an array with each entry controlling a section of the Ground Cover. If this is confusing, think of it like this as follows. The Ground Cover is a single object that is covering the entire terrain. The object itself is comprised of eight sections, Types[0] through Types[7]. Each section can be told what, where, and how to render a material or shape. You can feasibly have the Ground Cover object rendering simultaneously on eight different terrain layers.

With the above information in mind, you can assign the Ground Cover to terrain materials. Scroll through the properties until you get to Types[0]. Click on the box icon in the layer field. The Material Selector for terrains should appear. Select a material such as the dirt_grass shown here:

After you click the Select button, the Ground Cover will stop placing billboards on the entire terrain. It should now only be placing the foliage on the specific terrain layer you chose.

If you are having a difficult seeing this change, locate the maxElements field and increase the value dramatically:

Adding a Basic Sun¶

To add a Sun start by opening the Library tab in the Scene Tree dialog. Once the Library tab is active, click on Level sub-tab, then double-click the Environment subcategory.

Double-clicking the Basic Sun object will open the Create Object Dialog. From here, you can change a few basic properties, such as the name, starting color, and location. Enter a name then click the Create New button.

Basic Sun Properties¶

Additional properties can be changed with the Inspector pane. To change the Sun properties using the Inspector Pane click the Scene tab, then click the name of your new sun object. The Inspector pane will update to display the current properties of your new sun.

Azimuth and Elevation¶

The Azimuth and Elevation fields are very important to determining the global position of the sun, which affects the lighting intensity and shadow casting for every object in your level. You cannot think of these two fields as numbers that simply move your sun or make it higher. Azimuth and Elevation are actually angles:

Azimuth

Elevation (El) is measured between 0 and 180 degrees. It refers to the vertical angle measured from the geometric horizon (0°) towards the zenith (+90°).

• 0° will place the Sun at one end of the horizon as though it were just about to rise or set.
• 90° will place the Sun directly over the level, shining straight down.
• 180° will place the Sun at the opposite end of the horizon as though it were just about to rise or set.

Azimuth ranges between 0 and 360 degrees, and refers to a horizontal angle which determines the direction the Sun is facing in the level.

• 0° is true North.
• 90° is due east.
• 180° is due south.
• 270 is due west.

If you have a completely flat terrain with no objects, it will be difficult for you to visually measure the position of the Sun. You can use any object you want as a reference, but make sure you have your camera fixed on it to see the changes that you are making.

Adjusting Elevation¶

Go ahead and set the Azimuth and Elevation of the Sun to 0, which should give you a very dark level.

At this point, the angle of the Sun matches the horizon of your level perfectly. By increasing the elevation to 45, and you will see the objects in your level begin to cast short shadows. If you dont see the shadows changing make sure that you do not have more than one sun in your scene. The World Builder allows more than one sun in a scene, which obviously will change the light and shadows within a level.

Thinking back to angles, if 0° is parallel with the horizon, then 90° degrees will be directly overhead. Change the elevation to 90. You will see all of the shadows for the objects are directly below, just as in real life when the sun is sitting at zenith (straight overhead).

Setting the elevation to 180 will place the Sun at the opposite end of the horizon, once again resulting in a dark level. If you really focus, there is a slight change in shadow direction than when the elevation was 0°.

Adjusting Azimuth¶

The Azimuth of the Sun is measured clockwise from a fixed overhead perspective. To help you understand this rotation, we are going to adjust the Aazimuth of the Sun so that shadows of an object rotate like a sun dial or hands on a clock.

If you set the elevation to 45 and azimuth to 0, it will look like the shadow is pointing at 12 o’clock (if viewed from overhead).

Now, increase the azimuth by 45. At a sharp 45° angle, the shadow looks like it is pointing at 1 o’clock.

If you set the azimuth property to 90, you will notice a very familiar angle. The object and its shadow are forming a perfect right angle.

Half of a full rotation is 180°. After Setting the azimuth to this value, the shadow will now be pointing in the opposite direction from its original state.

Now, set the azimuth property to 270 and watch as the shadow points to 9 O’clock. The shadow should be pointing directly opposite from the 90° setting.

Finally, set the azimuth to 360. We have achieved full rotation. Careful examination will show that even though your shadows are pointing in the same direction as the 0° setting, they have been flipped.

Standard Lighting¶

The last topic we are going to touch on that is specific to the Sun object is standard lighting. Under the Lighting properties of the sun object there are three variables to adjust. Checking the castShadows box will cause surfaces to project shadows based on the direction of the sunlight. Removing the check will disable any shadows cast due to the Sun. If you uncheck that box you’ll see that the shadows you have been observing will not be displayed at all.

In addition to creating shadows, the light from the Sun will also affect the color shading of all surfaces in the level. There is a subtle, yet important difference between the color and ambient fields. If you want realistic lighting color, you will need to tweak both values.

The value of the color field will shade all surfaces that are in direct contact with the sunlight. A completely black color will make it seem like there is no light at all. Using the color picker to choose an orange hue will result in a sunset appearance for your level.

Ambient light is the available light in a space, whether from natural or mechanical sources. It is applied to everything in the world and also contributes to the direct lighting of the sun. The ambient field will lighten dark shadows and brighten well lit surfaces based on the color value.

Adding a Sky Box¶

To add a new Sky Box to a level change to the Library tab in the Scene Tree panel and double-click the Environment folder, locate the Sky Box entry then double-click it.

The Object Name is what you want your Sky Box to be called and will be displayed in the Scene Tree after it is created. The Material box allows you to select the starting material to use when creating the object.

Sky Box Properties¶

Additional properties can be changed with the Inspector pane. To change the Skybox properties using the Inspector Pane, click the Scene tab, then click the name of your new Sky Box object. The Inspector pane will update to display the current properties of your new Sky Box.

Adding a Scatter Sky¶

Every new mission starts with both Sky Box and Sun objects. Since the Scatter Sky object contains the functionality of those two objects embedded within it they must be removed in order to use a Scatter Sky in the level.

To create a new Scatter Sky, change to the Library tab in the Scene Tree panel. Click on the Level tab and select the Level folder. Locate the Scatter Sky entry and double-click it.

The Create Object dialog will appear. The Object Name is what you want your Scatter Sky to be named. It will appear in the Mission Group of the Scene Tree. Enter theSky as the name, leave the rest of the values at their defaults, then click Create New.

A new Scatter Sky object will be created and automatically added to your level. Therefore, it will once again have a sky. Since the Scatter Sky supplies a sun, the level should now be lit.

Scatter Sky Properties¶

Additional properties can be changed with the Inspector pane. To change the Scatter Sky properties using the Inspector Pane, click the Scene tab. Then click the name of your new Scatter Sky object. The Inspector pane will update to display the current properties of your new Scatter Sky.

Modifying Brightness¶

Remember to refer back to the properties as you proceed through the rest of this guide. It is time to modify some of the more important fields of the current ScatterSky object. After each change is demonstrated, you will be reverting back to the stock values to show how these modifications affect the object.

Now will start with adjusting the brightness of the sky and atmosphere. Under the ScatterSky section of the properties, look for the skyBrightness field. The default value is 25.

The skyBrightness field acts a global modifier of your brightness in the scene. Changing this value is similar to adjusting the contrast of a camera or monitor. Reduce the value to 5. This reduction will dramatically change the appearance of your level.

Now, greatly increase the value of skyBrightness to around 85. The view of your level should be extremely bright, as if the scene takes place in a desert at high noon.

If you have not already done so, revert your default brightness back to 25. You should change each value back to the default in this manner between each section of the remaining guide to see the effects of the next property.

Modifying Scattering¶

The scientific concept of scattering and how it affects your level is somewhat complex. The rayleighScattering and mieScattering values are extremely sensitive, and it is important that you have an understanding of how they work. The simplest way to explain scattering is to answer a question children often ask: “Why is the sky blue?”

In reality, beyond the atmosphere of the sky is blank space, that is, blackness. When you look up at the night sky, you can see the black of space and the stars it contains. However, during the day you see a blue sky. The blue color is due to the light rays from the sun being scattered by the molecules of the atmosphere as it passes through. Light appears to be white but it is actually composed of many different colors. The sky is usually blue because blue light scatters more easily than the other colors due to its physical properties.

The sky at the zenith is a darker blue than the sky near the horizon for two reasons. First, the atmosphere at this altitude is composed of much smaller particles, which is only capable of scattering the darker shades of blue light. Second, the light has had less opportunity to be scattered since it has not passed through as much atmosphere yet. The more times the same light is scattered, the paler the blue will become.

However, blue is not the only color that is scattered by the atmosphere, it is just the most common. Other colors, such as the reds at sunset, are due to how much atmosphere the light has passed through to get to your eyes. In this case, reds and blues are both being scattered but blue has been dissipated so much that it is no longer visible. The result is a red sky.

The scientific term for this light scattering effect is called Rayleigh Scattering, thus the rayleighScattering property of Torque 3D controls the color and darkness of the ScatterSky object.

The size and composition of particles in the atmosphere, such as dust and water, also has an effect on how light appears. Larger particles tend to scatter all colors of light approximately the same. This effect makes clouds, which are made of water vapour, appear to be white or grey. This is because the colors of the light are being scattered the same so that what you see resembles the original white form.

This type of scattering is also responsible for the clarity of a bright object and how the light rays are projected from it. The scientific term for this type of scattering is Mie Scattering, thus the mieScattering property of Torque 3D controls the clarity of light from bright objects such as the sun.

In summary, the scattering properties in Torque 3D are used to emulate the affects of nature. The mieScattering property affects the appearance of how light waves are projected from the sun object and the rayleighScattering property affects the color of the sky including how blue it will be.

Proceed to see the adjustment of these properties in action. Reduce the mieScattering field to a small value, such as 0.0005. You should notice that the scattering of the light around the sun object has been drastically reduced, resulting in a smaller and smoother sun.

Reset the mieScattering back to the default value (approximately 0.0045). Lower the rayleighScattering field to 0.0006.

The atmosphere of the sky should now be a darker shade of blue. Reducing the rayleighScattering value simulates two things. First, it simulates an atmosphere which reduces the colors of light that will be scattered limiting it to the darker blues. Second, it simulates an atmosphere that has had less opportunity to dissipate the light leaving the darker shade of blue intact:

At some point, you can reduce the value only so far before you hit a shade of blue that is almost completely black. This does not mean you are actually seeing the black of space, rather you are seeing the darkest shade of blue light which has not been dissipated at all.

Go in the opposite direction. Begin increasing the rayleighScattering until you hit a value of 0.008. This simulates two things. First, it simulates an atmosphere which allows more colors of light to be scattered. Second, it simulates an atmosphere that has had less opportunity to dissipate the light leaving paler shades of the light. The result in your level is a broader range of colors in your sky.

If you go too high with the value, your sky will eventually become black. This is due to the allowance of all wave lengths to interact with the atmosphere. The effect is known as the subtractive rule of colors: white is the complete lack of color (light interaction) and black is the presence of all colors. In other words, the atmosphere is absorbing all colors so you see black.

If you have become confused, there are quite a few resources in your local library and on the Internet you can look up to learn more. If you have gotten this far, but wish to keep it simple, remember the following:

mieScattering

Higher equals bigger and more scattered Sun. Lower equals smaller, smoother Sun.

rayleighScattering

Higher equals less blue sky. Too high equals black sky. Lower equals more blue sky. Too low equals black sky.

Modifying Colors¶

Move on to simpler concepts and property adjustments. The nightColor is a conditional property, as it only affects the scene during certain lighting conditions. As explained in the Sun documentation, modifying the azimuth and elevation will change the “time of day” for your level.

Go ahead and set the Elevation property in the Orbit section to 200, which will place the sun below the horizon. When the sun is no longer shining on your level, it is night time.

Scroll to the Night section in the Inspector Pane. Instead of manually guessing color values, click on the colored box next to the nightColor property. This action will open the Color Picker dialog. The dialog allows you to visually adjust the shade of your night time color. For an intense effect, go with an unnatural color such as red.

Click the select button when you are ready. Your level should immediately reflect the nightColor change you have made. Very creepy...

Definitely change the value back to something more suitable, such as deep blue/black color. Change the Elevation property in the Orbit section back to a number between 0 and 90 such as 45 to bring the sun back above the horizon and relight your scene.

Modifying Shadows and Light Intensity¶

There are two fields under the Lighting section that strongly influence how your scene appears. The first property, castShadows, can be toggled on or off. Clicking on the property to toggle it off will result in a blank box. With castShadows disabled, nothing in your scene will cast a shadow: objects, terrain, etc.

You can re-enable the shadows in your scene by clicking the box again, which will produce a check mark informing you that it has been enabled.

If you are using Advanced Lighting, the objects in your level will immediately begin casting shadows. If you are using Basic Lighting, you will need to relight the scene. Either way, the shadows will update according to the position of the sun.

The brightness field under the Lighting section is completely separate from the skyBrightness property in the ScatterSky section. Unlike skyBrightness, which changes the contrast of your entire scene (particularly the sky itself), the brightness property under Lighting directly affects your objects in the scene.

You can see how this property functions by adjusting the value. Increase the brightness to 1. The lighting in your scene should be much brighter. Additionally, the shadows in your scene will be much darker and more defined.

Notice how your atmosphere (sky and sun) did not change. Every other object in your scene should be better lit. You can remove the additional brightness by setting the value of the property to 0. The result is the additional, global brightness factor has been completely removed. Your lighting should now be minimal, and your shadows nearly invisible.

Adding a Basic Clouds Object¶

To add a Basic Clouds object: select the Library tab in the Scene Tree panel. Click on the Level tab and then double-click the Environment folder. Locate the Basic Clouds entry.

Double-click the Basic Clouds entry and a dialog will appear:

Enter a name for your clouds object then click the Create New button. A Basic Clouds object will be added to your level. Three separate cloud layers will be rendering and moving across the sky slowly:

Basic Cloud Properties¶

Additional properties can be changed with the Inspector pane. To change a Basic Clouds properties using the Inspector Pane click the Scene tab, then click the name of your new Basic Cloud object. The Inspector pane will update to display the current properties of your new sun.

Cloud Layers¶

While editing your Basic Clouds object, you may discover the need to view and edit individual layers. Open the BasicClouds section of the Inspector pane. Under the Layers sub-section you will find three layers labeled by an index. Each index refers to a layer and determines rendering order. The layer[0] will be rendered first, layer[1] next, and finally layer[2]. In simpler terms:

• layer[0] is drawn on top of the sky
• layer[1] is drawn on top of layer[0]
• layer[2] is drawn on top of layer[1].

You can adjust the visibility of each layer by toggling the layerEnabled property. If all three layers are disabled the Basic Clouds object will not be visible at all:

Layer 0 Disabled

Layer 1 Disabled

Layer 2 Disabled

Regarding Movement¶

Unfortunately, static images cannot properly show how the remaining fields affect the Basic Cloud layers, since they all pertain to the motion of the clouds. Clouds can only move horizontally, they can not move up and down. This horizontal movement is described in the texDirection property.

The texDirection property takes two values, separated by a space: “X Y”. Each value corresponds to the axis a texture should scroll on as well as the direction of movement on that axis.. The range of each value is -1.0 to 1.0. For example: A value of “1 0” will scroll the texture directly along the X axis in the positive direction with no movement along the Y axis.

A single property, texSpeed, controls how fast the cloud layer moves. If the property is set to 0, the cloud layer will not move. The higher the number, the faster your cloud texture will scroll across the sky.

With the texOffset property you can displace how the multiple textures line up or overlap with each based upon whatever looks visually best. For example, at the seam where the texture repeats, you might want that to be on the horizon rather than directly overhead. Adjusting the texOffset helps you visually adjust this. If you have a grasp of UV animation, this will come naturally.

Adding a Cloud Layer¶

To add a Cloud Layer object, select the Library tab in the Scene Tree panel. Click on the Level tab and double-click the Environment folder. Locate the Cloud Layer entry:

Double-click the Cloud Layer entry. The Create Object dialog box will appear:

Enter a name for your Cloud Layer object then click the Create New button. A Cloud Layer object will be added to your level. The three procedural cloud layers generated by the Cloud Layer object will be rendering and moving across the sky slowly:

At any time you can toggle the visibility of the cloud layer by locating the isRenderEnabled field under the Editing properties:

When you toggle this property, the clouds will render according to the status of the check box:

Cloud Layer Properties¶

Additional properties can be changed with the Inspector pane. To change a Cloud Layers properties using the Inspector Pane, click the Scene tab, and then click the name of your new Cloud Layer object. The Inspector pane will update to display the current properties of your new sun.

Cloud Layers¶

While editing your Cloud Layer object, you may discover the need to edit individual layers. Under the Textures property section you will find layers labeled by an index. Each index refers to a layer and determines rendering order. The layer[0] will be rendered first, layer[1] next, and finally layer[2]. In simpler terms:

• layer[0] is drawn on top of the sky.
• layer[1] is drawn on top of layer[0].
• layer[2] is drawn on top of layer[1].

Unlike the Basic Clouds object, you cannot toggle the visibility of each layer. All three work together for procedural generation.

Editing Cloud Texture¶

The very first visual modification you can make is selecting a texture. This is the first field under the CloudLayer properties. The stock Cloud Layer uses the following normal map:

Cloud Layer does not use a diffuse texture. Color is calculated per-pixel based on the normal map using the sun/ambient/fog colors. It is designed to work with the ScatterSky and TimeOfDay where simple/constant diffuseMap based color will not work. For the procedural layer to work, the texture needs to be 4-channel. RGB (red blue green) is a normal map and A (alpha) is the transparency.

Regarding Movement¶

Unfortunately, static images cannot properly show how the remaining fields affect the Cloud Layer since they all pertain to the motion of the clouds. Clouds can only move horizontally, they can not move up and down. This horizontal movement is described in the texDirection property.

The texDirection property takes two values, separated by a space: “X Y”. Each value corresponds to the axis a texture should scroll on as well as the direction of movement on that axis. The range of each value is -1.0 to 1.0. For example, a value of “1 0” will scroll the texture directly along the X axis in the positive direction with no movement along the Y axis.

Two properties control how fast the cloud layer moves: texSpeed and windSpeed. The windSpeed property is a global modifier, whereas texSpeed will affect a single layer. The two are added to each other to determine a layer’s final speed. If either is set to 0, the cloud layer will not move. The higher the number, the faster your cloud texture will scroll across the sky.

Adding a Water Block¶

To add a water block, switch to the Object Editor tool. Locate the Library panel and click it. Click on the Level tab and then double-click the Environment folder. Locate the Water Block entry.

Double-click on the Water Block entry. A dialog box will appear:

Enter a name for your Water Block then click the Create New button. A square body of water will be added to the scene. This is your Water Block. Like any other object, you can manipulate its transform using the gizmos.

Water Block Properties¶

Additional properties can be accessed with the Inspector pane. To change a Water Blocks properties using the Inspector Pane click the Scene tab, then click the name of your new Water Block object. The Inspector pane will update to display the current properties of your new sun.

Adding a Water Plane¶

To add a Water Plane, select the Library tab in the Scene Tree Panel. Select the Level tab and double-click the Environment folder. Locate the WaterPlane object.

Double-click the WaterPlane entry. the Create Object dialog window will appear.

Enter a name for your Water Plane, then click the Create New button. A new Water Plane will be added to your scene. If your entire screen fills up with a dark blue or black color, this means the WaterPlane was placed above your camera so that your camera is underwater. Just move your camera up to get out of the water.

This is typical if your objects are set to drop at or above your camera in the Object > Drop Location sub-menu.

Water Plane Properties¶

Additional properties can be changed with the Inspector pane and are identical to what you will find in a WaterBlock. To change a Water Planes properties using the Inspector Pane, click the Scene tab, then click the name of your new Water Plane object. The Inspector pane will update to display the current properties of your new Water Plane.

Adding Precipitation¶

To add Precipitation to a level, switch to the Library tab in the Scene Tree panel. Click on the Level tab amd double-click the Environment folder. Locate the Precipitation entry.

Double-click the Precipitation entry.The Create Object dialog will appear.

Enter a name for your Precipitation object. The Precipitation data field allows you to choose a datablock to start with as the basis for your new object. Click the drop down box for a list of available datablocks.

For the Full template, your only choice is HeavyRain so select it then click Create New. Your new Precipitation object will be added to your level, and rain will start falling automatically. The stock datablock for HeavyRain simulates a light shower, so you may not see much rain falling:

The HeavyRain datablock is located in the game/art/datablocks/environment.cs file. Its initial data contains the following:

datablock PrecipitationData(HeavyRain)
{
   soundProfile = "HeavyRainSound";

   dropTexture = "art/environment/precipitation/rain";
   splashTexture = "art/environment/precipitation/water_splash";
   dropSize = 0.35;
   splashSize = 0.1;
   useTrueBillboards = false;
   splashMS = 500;
};

We will get into manipulating the datablock later.

Precipitation Properties¶

Additional properties can be changed with the Inspector pane. To change a Precipitation objects properties using the Inspector Pane click the Scene tab, then click the name of your new Precipitation object. The Inspector pane will update to display the current properties of your new sun.

Adding Lightning¶

TODO

Lightning Properties¶

TODO

Adding Wind Emitter¶

TODO

Wind Emitter Properties¶

TODO

Adding Point Light¶

TODO

Point Light Properties¶

TODO

Adding Spot Light¶

TODO

Spot Light Properties¶

TODO

Adding Particle Emitter¶

TODO

Particle Emitter Properties¶

TODO

Adding Sound Emitter¶

TODO

Sound Emitter Properties¶

TODO

Adding a Ground Plane¶

To add a Ground Plane to a level, switch to the Object Editor tool and select the Library tab. Click on the Level tab. Double-click the Environment folder and locate the Ground Plane entry.

Double-click the GroundPlane entry.

A new GroundPlane will automatically be added to your scene. A “no material” orange texture will be applied.

Ground Plane Properties¶

Properties can be changed with the Inspector pane. To change a Ground Planes properties using the Inspector Pane click the Scene tab, then click the name of your new Ground Plane object. The Inspector pane will update to display the current properties of your new Ground Plane.

Modifying Scale¶

The material currently displayed on the object is a general warning texture:

You can change the way this material is tiled across the plane by adjusting the square size and UV scale. Scroll through the properties until you get to the Plane set.

Start by observing the squareSize. At 256, you will notice that each tile is large and stretching the material further. We can push more tiles per meter with tighter UV scaling. Set the squareSize to 128, then set scaleU and scaleV to 2.

The words on the material are much closer and appear to have been shrunken.

Changing Material¶

The warning material is a bit of an eyesore, so we will change that now. Click on the Material property in the Plane section of properties to bring up a list of available materials.

Select a material then click the Select button. Your GroundPlane will automatically be updated to use the new material you have selected.

That is the extent of your control over the material displayed on a GroundPlane. If you are using an extremely large texture, you could increase the squareSize and UV scale to make the tiling less blatant.

Interface¶

To switch to the Terrain Editor press the F2 key or from the main menu select Editors > Terrain Editor.

There are three main areas of the interface. On the far left is the tool palette, which is used to select what kind of modification you wish to make.

Grab Terrain

Allows you to manually raise or lower terrain under brush.

Raise Height

Adds dirt to terrain beneath brush, thus elevating it.

Lower Height

Excavates terrain below brush, thus lowering it and creating holes.

Smooth

Smooths jagged terrain beneath brush, creating more rounded elevation.

Smooth Slope

Smooth slopes in terrain.

Paint Noise

Creates random divots, elevation, and depressions under brush. Used for adding detail.

Flatten

Flattens terrain, elevated or excavated, to the level of brush’s starting point.

Set Height

Set terrain to fixed height.

Clear Terrain

Make holes in terrain.

Restore Terrain

Cover holes in terrain made with the Clear Terrain tool.

At the top, the Toolbar has updated to show various brush options. The brush options will change the intensity and pattern of your terrain modification.

Shape

Toggles between a round or square brush.

Size

Changes the size of the grid that makes up the brush, increasing or decreasing the amount of terrain being modified.

Pressure

Determines the amount of modification being applied to the terrain.

Softness

Determines how much of the brush is affected by the pressure and intensity.

Softness Curve

Customize how softness is applied.

Height

The brush starting height.

Finally, while moving the mouse over the terrain, you will see a circle drawn around the mouse cursor. This is the Terrain Editor brush and is controlled by your mouse. You can use this brush to “paint” your terrain adjustments by left clicking and dragging the cursor.

Brush Settings¶

Now we will go into deeper explanation of how the brush options can affect your terrain editing, and how the editor lets you know what you are doing. On the toolbar at the top of the screen, find the Brush Settings section.

Softness¶

The Softness setting directly affects the intensity of the entire brush’s surface. Like the others, it is represented by a slider. The number is a decimal value ranging between 0.0 and 100.0, with 100.0 being the softest and 0.0 the hardest.

The harder the brush is, the more dramatically the terrain under the brush will change. Think of a paint brush that has been dipped in paint and allowed to somewhat dry. The entire brush will be harder and thus will leave more paint behind than the same brush which has not dried and hardened. Since the entire brush has hardened the pattern that it leaves will be the same, that is more paint in the center and less at the edges, but the overall amount of paint will increase across the whole surface. If you allow the brush to completely dry then the entire brush will be the same hardness and thus will leave the same amount of paint across its entire surface.

Because you can not change the softness of a mouse cursor, the Terrain Editor provides the Softness settings to emulate these characteristics. Setting the softness to 0.0, meaning the brush has no softness at all, will result in the entire brush being hard. The edges will be just as hard as the center and so the entire brush will leave the same amount of change behind. The result will be in a sharp rise between the terrain and the brush edges, producing a cliff.

Conversely, if you set the brush to 100.0, meaning maximum softness the brush will exhibit its natural behaviour returning to very soft edges and a harder center. Setting the Softness to 100.00 (maximum softness) will cause the change at the edges to be much less dramatic than the change in the center and will result in a gentle rise from the edges to the center, producing a rolling hill.

Softness Curve¶

The previous section discussed how changing the Softness affects the brush over its entire surface mimicking the natural effects of a brush which is harder in the center and softer at the edges due to the distribution of its bristles. The Brush Softness Curve allows you to customize this behaviour further by changing the way softness and hardness is distributed within the brush.

Click the curved line next to the brush Softness slider. The Brush Softness Curve dialog box will appear.

The graph contains multiple nodes which can be moved by clicking and dragging them up or down. Modifying the nodes will determine which parts of your brush are hard or soft. As the graph shows, going from left to right will determine where in the grid you are changing the hardness.

Left nodes are closer to the center of the brush, and each node moving to the right will move toward the outer edges of the brush. The higher a node is situated, the harder it is. The following image is a visual of how this system works:

The circular pattern represents the shape of the brush looking straight on at its tip. Hardness of the brush is represented by red, softness by green, and yellow indicates variations in between. The node in the upper left represents the very center of the brush, since it is at the far left on the Inside-Outside axis. Because it is also at the very top of the Hard-Soft axis, it means that the brush is at its hardest at that location. So the combination of these two node positions indicates that the brush is at its hardest (indicated by red) in the very center.

On the other end of the graph line, the node in the lower right represents the very edge of the brush, since it is at the far right on the Inside-Outside axis. Because it is also at the very bottom of the Hard-Soft axis it means that the brush is at its softest at that location. So the combination of these two node positions indicates that the brush is at its softest (indicated by green) all around the edge.

If you were to drag each node so that the line is reversed, the brush will be softer toward the center and harder toward the edges.

To get an unusual setting, you can create a “wavy” version of the curve. Alternating the nodes in extremes from top to bottom, will result in rings of softness with the brush.

Now that you are familiar with the interface, it is time to edit the terrain.

Grab Terrain Tool¶

Let’s start by selecting the Grab Terrain tool from the palette. With the Grab Terrain tool, you can move a section of terrain up or down depending on which direction you are dragging your mouse.

Use the circle brush, size 20, 100 pressure, and 100 softness. Hover your brush over a section of terrain, hold down the left mouse button, then move your mouse up. The terrain should dynamically adjust to your cursor location.

When you are satisfied with the height, let go of the mouse to see your terrain modification.

Use the mouse to cover part of your new adjustment with the brush. Notice how the brush clamps to the terrain, maintaining the shape you are using while still selecting a section.

Despite the elevation of your current selection, the section under the hardest part of the brush will still adjust more dramatically. Using the default Softness Curve, if the center of the brush is just to the edge of a hill, you can adjust nearby terrain to match elevation. Terrain under the softer part of the brush will still elevate, but not as much.

Before moving on to the next tool, we will experiment with the softness value. Set the softness of your current brush to 1 (very hard). Move the brush over a flat section of the terrain.

Click on the terrain and drag your mouse up. Instead of an elevated hill with a smooth slope, your brush should have created a flat plateau with completely vertical sides. With a softness of 1, your brush’s shape will be used to extrude the terrain in a sharp manner.

Raise Height Tool¶

The Raise Height tool can only elevate the terrain, but it does so in a very controlled manner. Instead of manually lifting, you can “paint” the terrain in a sweeping motion by dragging the mouse while holding the left button. The longer you keep the brush in one location, the higher that section will be and the higher the Pressure setting, which was reviewed earlier, the faster it will change.

Set your brush size to 20, pressure to 40, and softness to 100. Find a flat section of the terrain and move your mouse cursor to that location to hover the brush.

When you are ready, click and hold the left mouse button and begin dragging your brush in a direction. The terrain should elevate wherever your brush passes over. You can use this to create a hill over a long section of terrain.

Using a lower brush pressure results in less dramatic terrain elevation as you “paint”. This allows you to be more exact in cases where you need to.

Lower Height Tool¶

The Lower Height tool functions completely opposite of the Raise Height tool. Instead of elevating, you can dig holes in the terrain with this tool. Again, use a circular brush with 20 size, 40 pressure, and 100 softness. With the Lower Height tool selected, locate a flat section of the terrain and hover your brush over it.

Click and hold down the left mouse button. As you do so, the terrain will sink down below the brush. If you sweep your mouse as if you are painting, you will create a path of lowered terrain. The longer you hold the mouse in a single location, the deeper the hole will be.

Smooth Tool¶

The Smooth tool erodes jagged terrain sections under the brush to create a smoother surface. This tool will only work if you sweep the brush across a surface. Simply holding down the left mouse button will have little to no effect.

Keeping the same settings we have been working, locate a jagged section of terrain. If you have to, create one with the Raise Height tool first. Make sure the elevation difference is significant. Select the Smooth tool then hover the brush over the applicable terrain.

Click and hold the left mouse button, then make small circles around the peak of the terrain section. The tip should lower and have a broader surface. The broader your sweep, the more terrain is affected by the smoothing process.

Paint Noise Tool¶

The Paint Noise tool is used to give your terrain modifications a more randomly defined look. The tool uses a noise algorithm for sporadic elevation and excavation. Essentially, it causes fluctuation in the amount of terrain it modifies and how intensely it changes.

Select the Paint Noise tool, then set your brush to size 15, 50 pressure, and 100 softness. Locate a large section of flat terrain and move your camera to a high elevation.

Click and hold the left mouse button down then begin to “paint” the terrain by dragging it in random patterns. Try making several concentric circles, varying spirals, zig-zag motions, etc. You should eventually see some definition forming.

When you are finished with the tool, fly your camera around the section of the terrain to see how the terrain was affected. Keep in mind that most of these changes were random, which can add much needed detail to your terrain but can cause some weird effects. The Smooth tool can be used to go back and blend out any such effects that do not look natural.

You can use this tool on terrain that has already been modified to remove unrealistic adjustments, such as perfectly smooth or flat slopes.

Flatten Tool¶

The Flatten tool is used to make the terrain surrounding the brush’s starting point be equal to that points elevation. In other words, this either lower or raise your terrain to the same elevation as that starting point.

Use a circular brush with 15 size, 50 pressure, and 100 softness. Find a section of terrain that is elevated. Position your brush near it, but on a flatter section of the terrain.

Click and hold your left mouse button, then drag it toward and over the elevated terrain until you have swept over most of it. You should see that the tool has flattened a strip of terrain, based on the brush’s location as it swept. The flattening process will become weaker the further you take the brush into the higher terrain such that it will not cut a path that is exactly the elevation of the starting point but rather relative to it and the terrain you are crossing. If you sweep the Flatten tool slowly across a hilly terrain, you will see that it is well suited for specialized tasks such as creating road and rail beds or mountain passes. Creating these types of features can be accomplished using the other tools but this tool in particular makes that job much easier.

If you make several sweeps in the same direction, from the same starting point, your terrain will eventually smooth out into a flat plateau almost level with your original starting point.

This is generally handy for clearing a smooth path from one elevation to another. However, this is not the optimal approach for flattening huge sections of terrain. The other tools can perform that process much faster and more efficiently.

Set Height Tool¶

The Set Height tool will allow you to determine the exact height for the terrain brush. Use a circular brush with a size of 15, pressure of 50 and softness of 100, and a height of 520.

Now, when you press the left mouse button, it will create a plateau at exactly that height.

Clear Terrain Tool¶

The Clear Terrain tool will allow you to remove pieces of the terrain. This is an effective way to carve out entrances to caves. That way your artist can create a detailed cave level and your level editor can “carve” out an entrance in the terrain. Using the previous tools, create a small hillside.

Now, set your brush size to 5 and zoom into an area that looks like a promising cave entrance.

When you select the terrain area, it will remove the mesh data from the terrain, creating an opening.

Now you can place your cave model underneath the terrain so that the player can explore the world under your terrain.

Restore Terrain Tool¶

The Restore Terrain tool complements the Clear Terrain tool. It will restore the mesh data for the terrain. That way, you can have better control over the transition between your models and terrains. If you select the Restore Terrain button and then left-click on the previously cleared area, you will see it restore the terrain to its previous state.

Interface¶

To switch to the Terrain Editor press the F3 key or from the main menu select Editors > Terrain Painter.

There are four main areas of the interface you will focus on while using this tool.

The Brush¶

Using the Terrain Painter is very similar to painting on a piece of paper with a brush except here you are painting on the terrain by dragging the mouse across the screen. Your brush is represented as a circle or a square in your scene’s view. This visual outline allows you to know where your brush is located and what portion of the terrain it will affect when you move it.

The image shown above is displaying the default brush style when you first open the Terrain Painter. If you wish to change your brush type, you can modify it via the Brush Settings found in the Tool Settings toolbar at the top of the screen. Brush Settings are only active while using the Terrain Painter.

The image shown above is displaying the default brush style when you first open the Terrain Painter. If you wish to change your brush type, you can modify it via the Brush Settings found in the Tool Settings toolbar at the top of the screen. Brush Settings are only active while using the Terrain Painter.

You will find the Brush Size slider next to the shape settings. You can move the slider from left (smaller) to right (larger) to change the size. The stock value is typically small, usually a 9x9 grid. The more you increase the slider value, the greater the grid will grow. The change will add an equal number of rows and columns, as shown below.

You can find the Terrain Painter palette docked on the right side of the editor. This panel is similar to a traditional painter’s palette in the real world. Instead of swatches of color, the Terrain Painter’s palette is populated by TerrainMaterials which you use to paint the terrain.

A TerrainMaterial is a collection of three textures combined into a single layer. The three textures are the base (also known as diffuse), detail, and normal map. A preview of which TerrainMaterial (or layer) is shown in the box at the top of the palette labeled Terrain Painter Material Preview.

Terrain Materials Editor¶

When you wish to add a new TerrainMaterial, click on the New Layer entry in the palette. Once you click on the entry, the Terrain Materials Editor window will appear. This tool is completely separate from the basic Material Editor, as TerrainMaterials are structured and used much differently than other Torque 3D materials which are used on shapes in the world placed with the World Editor.

Terrain Materials

The TerrainMaterials list contains all the currently available textures for creating terrain materials.

New Button

Clicking the Page icon in the Terrain materials header creates a new TerrainMaterial entry for editing.

Delete Button

Clicking the Trash can icon in the Terrain materials headerdeletes the currently selected TerrainMaterial.

Apply & Select Button

Clicking this button closes the Terrain Materials Editor and returns to what ever operation brought you to the dialog, for the purposes of this article it returns you back to the Terrain Painter Material Selector and adds the selected TerrainMaterial as a new material ready to be used for painting.

Cancel Button

Close editor without making a choice.

Clicking on an entry in the Terrain Materials list updates the Material Properties pane on the right to display the current properties of that material.

The Material Properties pane contains a Name field, which is used as the label assigned to the material and three sub-sections which describe the textures that define the material.

The Diffuse sub-section shows a preview and the properties of the materials Diffuse texture, which provides the color and base appearance of the material. The Diffuse texture is also commonly referred to as the Base texture for this reason.

The Detail sub-section shows a preview and the properties of the materials Detail Map, which gives the material a more defined, crisp look. If you are familiar with advanced rendering concepts this is accomplished using additive blending and per-layer fade distance techniques.

The Normal sub-section shows a preview and the properties of the materials Detail Map, which gives the material a more defined, crisp look. If you are familiar with advanced rendering concepts this is accomplished using additive blending and per-layer fade distance techniques.

Name

Assigns the name of the TerrainMaterial which will appear in the Terrain Materials list.

Edit Button

Clicking this button allows you to select the texture to assign to this aspect of the material.

Trash Can Button

Clicking this button clears the texture that has been selected for this section.

Use Side Projection

Terrain diffuse textures are normally applied top-down, which can result in stretching. This toggle causes a material to smoothly merge and conform to steep terrain if needed.

Diffuse Size

Controls the physical size, in meters, of the base texture.

Detail Size

How close the camera must be before the detail map begins rendering in meters.

Detail Distance

Determines how bold the detail appears on the base texture.

Parallax Scale

Adjusts the intensity of the parallax depth in normal maps.

Painting¶

Before we begin painting, we will add a second TerrainMaterial to our palette (if the project you have open already has more than one feel free to skip this step).

To add a new material click the New Layer button in the Terrain Painter Material Selector. The Terrain Materials Editor will open. Click any TerrainMaterial in the list other than the one that is already in your palette, such as the “rocktest” material shown here.

Once you have the material selected, click the Apply & Select button. Once you have done this, the new layer will have been added to your palette and available for painting.

This is a good time to take a look behind the scenes to understand a little of how Torque 3D organizes materials and how it uses them for other operations to your advantage.What you can not see in the interface is that the system has associated each of the TerrainMaterials in your palette with a numbered layer. Throughout these documents you will see, or may have already seen, that material layers are used to control aspects of object placement such as which layer automatic object placement will occur on.

If you started with a project that was created with the Full template and added the rocktest material in the last step then the system now considersgrass1 to be layer0 and rocktest to be layer1. This allows you, whenever asked, to select layers using something meaningful to you rather than remembering some random numbering system. When asked to select a layer you can simply pick the grass or rocktest layer from a list and the system will use and apply the proper numbered layer to perform the related operation.

All this becomes very important in reducing the amount of work that is needed to create realistic terrain. The TerrainMaterials that you apply with the Terrain Painter tool not only give the terrain the appearance of natural materials but they can be used to automatically generate and restrict foliage and other shapes when used in conjunction with objects such as GroundCover.

Now, on to learning to paint. Make sure you have the new material selected in the Terrain Painter Material Selector. So we can more easily see the modifications we are about to make, set your brush size to about 25. Now, find a section of the terrain you wish to paint. Here, we started in a corner of the TerrainBlock.

Click and hold down the left mouse button, then begin dragging the brush around the screen in a sweeping motion. The terrain will update in real time to reflect the painting of the new TerrainMaterial. When you let go of the mouse button, the Terrain Painter will stop laying down the material.

You should have noticed that your brush clamped to the terrain as long as the cursor was over the block. This happens regardless of any terrain modification or elevation occurring, as shown in the following example. Notice how the brush distorts to wrap around the elevated terrain.

Even though you just paved a large section of rock material, you can still paint over it. Decrease the Brush Size to approximately 9, so we can paint a more exact line of terrain. We are going to paint a path over our rocky area. In the Terrain Painter palette, select the first material (desert_sand_03 in this image).

Now, using your mouse cursor move the brush to the edge of our rocky area. You can start it just before the rocky area, or even on top of it.

Click and hold down the left mouse button to begin painting then sweep your mouse in a curving motion across the rocky area. When you are finished, let go of the mouse and examine or your winding path made of grass.

If you were to drop down to the player’s camera view, you can see where the two TerrainMaterials meet each other after editing.

Take the time to experiment with different brush sizes and shapes to see what kind of patterns you can come up with. When you are ready, read on to learn how to add a new TerrainMaterial with higher quality and detail.

Interface¶

To switch to the Material Editor press the F4 key or from the main menu select Editors -> Material Editor.

Material Selector¶

When you wish to swap the material mapped to an object or create a new material, you will use the Material Selector. To change the material on an object, it must first be selected. If you do not know how to select an object, refer to the Object Editor documentation, then switch back to the Material Editor (F4). The Material Properties pane on the right side of the screen displays the properties that describe the material of the selected object.

At the top-right of the pane there is a value named Material. Click on the globe to the right side of it. This will bring up the Material Selector window.

The center section of this dialog displays a list of all materials currently loaded in the game. OClicking on any material selects it which will cause the panes on the right to update and display information about the material. This information is limited to a preview of the material’s Diffuse texture, the name of the diffuse texture, and a list of filter tags.

On the left is a list of filters. The filter system is used to organize your materials for ease of use, and contains types and tags. To create a new tag, click the new tag button:

The Create New Tag dialog will pop up. Enter a name for your new the tag then click the Create button. In this example, you will be grouping all the materials related to cliffs. Whenever a material is selected, the Material Tags section on the right will be updated to show all the tags that you have created, each with a checkbox. Clicking the box of a specific tag will associate that tag with the current material. Clicking a checked box will dissociate the tag from the material.

The list of materials can be filtered using the tags assigned to them. To filter the material list use the tags section on the far left. When you click on the check box for tag it tells the system to include materials that have that tag in the list. Any materials that do not have at least one of the checked tags will be filtered out of the list.

Editing an Existing Material¶

Your game’s levels can potentially contain thousands of different objects with varying purposes: explosive barrels, ammo crates, static light fixtures, solid walls, etc. Each one will have a material that might need subtle tweaking to fit in, such as a glowing light bulb.

In this example, you will adjust the properties of this bridge materials.

Remember that you can preview the changes in the scene as well as the preview box in the Material Editor. You will start by toggling the Specular property of the material used for the metal pipe. Without Specular enabled, an object will not have a shine and will thus appear flat.

When the Specular property is enabled, the cube in the preview box will have a shiny appearance. In the scene, the metal will also be shinier due to the lighting reflection.

Creating a New Material¶

While developing your game, you will most likely be using your own assets. When you add a model to the scene, it will be assigned the default “No Material” texture which serves as a warning to the designer that no material has been assigned to an object. This material is automatically used for all assets before they have a mapped materials.

If you have already created the textures for your object, creating and assigning a material is a simple process. Start by clicking the globe symbol next to the Material name box.

The Material Selector dialog will appear. Click the Create New Unmapped Material button found at the top right of the Material section’s header.

A new material will be added to the list with a name similar to newMaterial_0. Click on the material to view it in the Diffuse Preview section.

Click the Select button to use that selected material for the object you are editing. After the Material Selector closes, you will be prompted to save any material changes that you may have made before entering the Material Selector. Do so if you wish to retain any changes that you made prior to creating the material.

Your new material will have replaced the material selection in the Material Properties pane back in the Material Editor and should now be displayed in the Material field. Type in the real name you want for your new material to be known by then press the Enter key. In this example, the name of the material is “boxxy.”

Before editing anything else, click the Save Material button, represented by the floppy disk symbol to save the new material.

Now, scroll down to the Texture Maps section of the Material Editor. This is where you will be adding the actual texture files that define this new material. Click on the Diffuse Map preview or the Edit button in that section to open a file browser. Navigate to your diffuse texture, or sometimes referred to as the base texture. Select the file that you want to use as for this new material then click the Open button.

Your preview window and scene should immediately be updated to reflect the addition of your texture.

Repeat the process to add your Normal map. Click on the preview or edit button in the Normal Map section. When the file browser appears, select your normal map texture. Once again, your scene will be updated to reflect the changes that have been made to the material. Click the save button to retain these changes.

If you open the Material Selector again, you will notice your new material has been saved in the list. This material is now available to be assigned to any other meshes within the project without having to go through the whole process of redefining it again.

Interface¶

To switch to the Material Editor press the F4 key or from the main menu select Editors > Material Editor or click on the orange box icon to get started.

The Tools Palette will populate with basic manipulation icons:

Select Object

Select a convex object or individual face

Translate

Move an individual face

Rotate Object

Rotate an individual face

Scale Object

Grow or shrink an individual face

As with the other editors, extremely helpful usage hints will be displayed in the bottom left corner of the editor. Shortcuts and basic descriptions will appear based on which tool you are using.

Creating a Convex Shape¶

The very basic interface allows you to quickly sketch out convex shapes. All of your editing can be performed via mouse actions. To begin creating a convex shape, hold down the Alt key and left mouse button to begin drawing a base. The base will follow where your mouse cursor is being dragged, shrinking or growing as it goes.

Once you let go of your mouse button, the base will stop growing. From here you can move your mouse cursor up and down to change the height of your new box. You do not have to hold down the mouse button during this time.

Once you are happy with your convex shape’s height, left click one last time. The box will become a solid object and automatically be selected. If you make a mistake, hit Ctrl-Z to undo and erase the shape then repeat the process.

When you are ready to begin shaping the box, left click one of its faces. The currently selected face will be highlighted in bright pink:

At this point, you can start using the Sketch tools to edit the specific face you have selected.

Editing a Convex Shape¶

Let’s move some surfaces around. Start by selecting a faceof the object by (left clicking on it). Three colored lines will now extend from the center of that face - these represent the axes for the three dimensions x, y and z. This is called the axis gizmo. Activate the Move Selection tool by clicking the icon on the Tools Palette on the left of the screen or press the shortcut key 2:

Once the Move Selection tool is activated, arrows will appear on the ends of the axis gizmo. Click on the X-axis and drag it outward. Your face will move in the direction you are dragging your mouse. The entire convex shape will adjust according to where the face as moved. You will be able to move the face in any direction in three-space:

Next, activate the Rotate Selection tool by clicking the icon on the Tools Palette on the left of the screen or press the shortcut key 3. A spherical gizmo will appear representing the orientation manipulators. The axis gizmo straight lines will now be displayed as three curved colored lines:

Click and hold one of the colored lines (an axis), and drag it in a direction. The selected face will begin to slope according to the new orientation:

Finally, activate the Scale Selection tool by clicking the icon on the Tools Palette on the left of the screen or pressing the shortcut key 4. Click on the top face of the box. A squared like gizmo will appear which will allow you to choose what parameters to adjust. You can adjust the (width, height, depth, or any combination of the three):

Instead of adjusting one parameter at a time, we are going to adjust width and height. Move your mouse over the different squares to see how they highlight. Click the bottom square of the gizmo, in between the red X and yellow Y axis and hold down the mouse button. Drag your mouse in either direction to shrink or grow the face. The more you shrink, the more like a pyramid it will be come:

The last action this guide will address is extruding. The Sketch Tool extruding feature creates new geometry from a selected a face. Start by creating a new convex shape - review the section, Creating a Convex Shape, if you don’t remember how.

Next click on a single face of the shape. Make sure you have a face selected, and not the entire object. The selected face should be highlighted with a in bright pink. Activate the Move Selection tool. A hint will display at the bottom of the editor: “Move selection. Shift while beginning a drag extrudes a new convex.”

Perform this action as described. With the face selected, hold down the Shift key, move the mouse over one of the colored arrows, and click and drag outwards from the object. The exact dimensions of the original face will be duplicated, constructing a new convex based on those parameters. This may not be apparent until you click on a face and see that the area of the new face is separate from the original:

You can now select faces on the new convex object and continue editing it as a new object:

Object Manipulation¶

When you are finished sculpting a convex shape, you can manipulate it as you would with any other game object using the Object Editor. This includes selection, translation/rotation/scaling, and editing specific properties.

Unlike the Sketch Tool, selecting a convex shape using the Object Editor it treats the object as a whole. There is no individual face selection. Switch to the Object Editor by pressing the F1 key then click on one of your objects:

You may then manipulate the object using the normal Move Selection, Rotate Selection, and Scale Selection tools of the Object Editor. You can even use the other more complex Object Editor commands such as copying an object. To copy the object: hold the Shift key; activate the Move Selection tool by pressing the 2 hotkey; press and hold the Shift key; then drag the mouse to a new position in any direction. When you release the mouse button you will have a new duplicate copy of the original object:

This can also be used for mass production of objects by copying multiple objects at once. Change back to the Select Arrow tool by pressing the 1 hotkey. Click one of your objects to select it. Take note of the position of the gizmo that appears and the little cube at the gizmos origin. Now select the other object. Again take note of the position of the gizmo and the cube for this object. Now press and hold down the Shift key then click your other object again. You will notice there are now two small cubes, one over each object, and one gizmo relatively near the center of the two objects. This indicates that both objects are currently selected. You now have a selection group.

Change to the Move Tool by pressing the 2 hotkey. The cubes will disappear, and large arrows will appear on the ends of the gizmo. If you mouse over either object, you will see a faint transparent cube pop up. This indicates that object is a part of the selection group. Clicking any arrow and dragging the mouse will not move all the objects at once. Likewise, pressing and holding down the Shift key, then clicking and drag will duplicate all the objects in the selection group:

The new copy of the objects will now be the current selection and they can be moved as a group or immediately copied again with another Shift-drag operation. The above method combined with rearranging the individual objects after copying them is a great way to piece together multiple convex shapes to create more complex arrangements. For example, you might have unique convex objects for a roof, wall, chimney, and so on. You could only create one wall, then duplicate it four times so that they are all the same size then arrange them into a building with the Move Selection tool:

Once you get the hang of the Sketch Tool, you can sculpt unique and complex shapes. Entire levels can be prototyped to use placeholder art, created right inside Torque 3D, while you or your artists work on the final assets using the tools that they are familiar with.

Interface¶

To switch to the Datablock Editor press the F6 key or from the main menu select Editors > Datablock Editor. Or alternately click the Datablock icon from the World Editor toolbar.

The Datablock editor has two components: the Datablock Library pane and the Datablock properties pane. These panes appear at the right of the screen whenever the Datablock Editor is active. The Datablock Library pane is further divided into two tabs. The first, labelled Existing, contains a categorized list of all the existing datablocks. The second, labelled New, is used to create new instances of those datablocks.

Clicking any existing datablock will cause the Datablock properties pane to update to display the current properties of that datablock.

The image below shows the selection of the DefaultCar datablock, under the WheeledVehicleData category. This datablock contains variables related to vehicle performance.

Creating a new Datablock¶

Creating a new datablock can be done by creating a copy from an already existing datablock. To do so first select the New tab in the Datablock Library pane.

Then choose the type of datablock you wish to create from the list. Then press the New icon.

You will be presented with a new window giving you the option to name the new datablock and to copy values from one of the existing instances of the datablock type, if you want to. For example, in this scenario the DefaultCar datablock would be available in the dropdown box because it already exists at the time when creating a new datablock.

After clicking the Create button a new copy of the datablock will be added to the library, under the datablock type you first selected. In this example, you will create a new WheeledVehicleData datablock and name the new version “raceCar”. This new version can now be found in the Library, under the Existing tab, in the WheeledVehicleData section.

Saving a Datablock¶

After editing the new datablock or any other datablock, you will need to save it. You will see a small “*” in the header of the properties right after the Datablock label if the datablock needs saving.

Click the small floppy disk icon to save your datablock changes.

Deleting a Datablock¶

If you no longer need a datablock you can easily delete it by selecting the Delete icon.

After pressing this icon you will get a notification window stating that the datablock has been removed. The World Builder will need to be restarted to completely remove the file.

Interface¶

To access the Decal Editor press the F7 key or select it from the drop down menu at the top of the World Editor, by choosing Editors > Decal Editor. Or select the Decal icon from the World Editor tool bar.

The Decal editor has two main parts, one where you can add and manipulate the size, rotation and position of the decal, and the other for adjusting the decal properties. On the upper-left hand side of your screen, you’ll see a toolbar which provides tools for decal placement and manipulation. On the right of the screen, there is the Decal Editor pane which displays a list of decals, and the Template Properties pane below it, which displays properties of the selected decal along with a texture preview.

In the Decal Editor pane on the top right, under the Library tab, is a list of the decal datablocks defined in the system, which are really decal descriptions. In the Instances tab, there is a list of all decals that have been created within the current project.

Adding a New Decal Datablock to the Library¶

Before you can paint a decal to your world, the datablock needs to exist in the decal library. To add a new decal, simply press the New Decal icon at the top of the Decal Editor pane. This will add a new blank decal to the library, ready for you to select or add a material and set up its properties.

Naming a New Decal Datablock¶

After creating a new decal you will want to name it. This can be achieved by selecting the name property and entering a new name, then pressing the Enter key.

Removing Decal Datablock from the Library¶

To remove an existing decal from the library simply select the decal in the list then click the Delete icon.

If you select Yes all instances of the selected decal will be removed. The datablock will continue to exist until the World Editor is restarted.

Missing Decals¶

If a decal exists in the level, but is not rendering, it means the datablock for it has either been deleted, renamed, or corrupted. The Retarget button allows you to assign an existing datablock to a missing decal.

To open the retarget dialogue, select the decal that you wish to fix then click the Retarget icon at the top of the Decal Library pane.

The Retarget Decal Instances dialog box will open. From here you can reassign the decal datablock. Select a Decal Datablock from the drop down list that you wish to use for the selected decal.

Editing Tools¶

The Decal Editor placement and manipulation tools appear on the toolbar down the left of your screen whenever the Decal Editor is active. Each tool can be activated by clicking the appropriate icons or by pressing its hotkey. Hotkeys are assigned 1 through 5 from top to bottom in the toolbar and are visible by hovering the mouse over the icon. These tools will enable you to quickly place, scale and rotate your decals.

Properties¶

A Decal has only a small amount of properties which can be edited using the Template Properties pane:

Size

The size of the decal rendered onto the surface.

Material

Specifies the Material selected to display as the decal.

Lifespan

Time in Ms (milliseconds) that the decal will exist in the world after being placed dynamically.

FadeTime

Time for the decal to fade out in Ms (milliseconds).

Frame

Index of texture rectangle to use for this decal, if the texture consists of multiple images.

Randomize

Randomizes the texture rectangle (frame) used for each instance of the decal. So it essentially uses a random frame.

TexRows

Defines the number of image rows in a multiple image material.

TexCols

Defines the number of image columns in a multiple image material.

ScreenStartRadius

Distance check for rendering the alpha channel of the decal.Visibility check based on the scale of the decal

ScreenEndRadius

Distance check for rendering the alpha channel of the decal.Visibility check based on the scale of the decal

Render Priority

If more than one decal are on top of each other the decal with the higher priority will rendered first

Clipping Angle

The angle in degrees used to display geometry that faces away from the decal projection direction.

Interface¶

To access the Forest Editor press the F8 key, or select it from the drop down menu at the top of the World Editor, by choosing Editors > Forest Editor, or click on the leaf icon to get started.

The Tools Palette on the left of the screen will populate with Forest Editor specific tool buttons represented by icons.

Select Item

Select an individual object in forest

Translate Item

Move the currently selected object

Rotate Item

Rotate the currently selected object

Scale Item

Grow or shrink the currently selected object

Paint

Used for painting objects on terrain

Erase

Used for erasing objects from a terrain

Erase Selected

Used to delete the currently selected objects

The Forest Editor has two main panels which will appear on the right of the screen whenever the Forest Editor is active.. On the top is the Forest Editor pane which is divided into two tabs: Brushes and Meshes. The Forest Editor works in a manner similar to painting on a canvas with a brush, except instead of paint the Forest Editor lays down shapes onto the terrain of your level. A Brush in the Torque 3D Forest Editor is composed of one or more mesh elements, which can be alternated between when painting.

The Meshes tab contains a list of all Forest Mesh elements which can be assigned to a brush. A forest mesh is really a datablock which is an information structure that defines a model and the properties which control it in the forest.

On the bottom of the right side of the screen is the Properties pane. The Properties pane displays information about the currently selected element in active tab of the Forest Editor pane.

Before we can use these tools and paint a forest, we need to import a forest mesh and set up a brush.

Creating a Forest Mesh¶

To create a forest mesh tart by clicking on the Meshes tab in the Forest Editor pane. There are two icons in the top right. The trash bin deletes the currently selected existing mesh, and the leaf icon will adds a new mesh. Click on the Add New Mesh icon.

A file browser should appear. Locate the sample tree mesh file, defaulttree.DAE, which can be located in the game/art/shapes/trees/defaulttree folder.

A new mesh will be added to the tab using the same name as the file you selected:

The Properties pane will also be populated with fields and values which describe the new mesh.

Switch to the Brushed Tab. You will see that the new mesh has also automatically been added to the list of Brushesallow you to select it as the element to paint with.Select the new brush by clicking on its name. The Properties pane will be updated to display the properties of the brush which can be used to randomize the placement and appearance of the selected mesh.

Using a Brush¶

Now that you have an available brush you can begin painting a forest. Select the defaulttree brush from the sample assets. Move the mouse until a blue circle appears on the terrain. This is the outline of your forest brush and shows where you are going paint. To begin painting, left click the mouse and drag it around on the terrain.

If this is the first time you have painted a forest in a level then no Forest object exists in the level yet. However, a forest object must exist , so you will be prompted to confirm that you want to add one.

Answering No will abort the forest painting operation. Answering Yes will automatically create a new Forest object, add it to your level, and return you to the level with the brush still active ready to continue painting. You can examine the forest object the same way as any other object using the Object Editor but it has no useful properties to edit so lets skip it for now an continue on with our forest painting operation.

Once again, hold down the left mouse button and drag the mouse over terrain. As you move the brush trees will begin showing up in the wake of your brush. To change the size of your brush, pull the mouse wheel toward you to increase the size or push it away to decrease the size. The blue circle will grow or shrink to indicate your new size.

Note that you do not have the ability to move the camera forward and back in the Forest Editor because of the availability of the brush resizing feature. To move the camera forward and back while using the Forest Editor press the Up Arrow to move forward and the Down arrow to move backward.

Keep painting until you have a decent patch of trees:

If you move your camera down to ground level, you can see how your forest will look from a player perspective. Youll notice that these are full 3D objects that react to collision, sunlight, and external forces.

Adjusting Properties¶

You can edit the properties of a Mesh to adjust how each tree is placed when painting. To adjust the density of mesh placement switch to the Meshes tab then select your defaulttree entry. The Properties pane will update to display the properties of your mesh. Change the radius property from 1 to 2 then press the Enter key.

This radius tells the tool a rough amount of space this item takes up. The value is a decimal value and has no limits, but remember that if the value is too low your trees may overlap, and if it is too high you may not get any trees to appear because the spacing might be larger than the brush itself. Now when you paint you should get more spacing between the placed meshes.

As mentioned previously, you can use the Forest Editor to paint additional environmental objects such as rocks, shrubs, or any other 3D model. Since you can paint different types of objects, you might want to organize your brushes and meshes.

In the Brushes tab, click on the Add New Brush Group icon. This will add a new entry in the brush list, called “Brush”. Click on the text of the new brush group. This will allow you to edit the text of the brush. Name the brush group “Trees” then press the enter key. Now, you can click on the defaulttree element and drag it onto the Trees brush group. Switch to the Meshes tab, and click the Add New Mesh tree icon to add a new one. Select game/art/shapes/rocks/rock1.dts as your model.

The rock1 mesh will be added to your Meshes list. Unlike trees, the rock1 mesh is fairly large and somewhat spherical. Spreading out the placement of this mesh will help prevent dense blobs of rocks being placed. In the Mesh properties tab, increase the rock1 radius to 3.

Switch back to the Brushes tab. Create a new brush group and name it Rocks. Your rock1 mesh element should already be in the list, so drag it onto the Rocks brush group to keep things organized. Go ahead and paint down some rocks in your level. You should end up with a patch of huge boulders with fairly even spacing:

You might have noticed all the boulders are the same size. For added realism, you can adjust the brush properties to randomize its appearance. Select rock1, then decrease the scaleMin and increase the scaleMax. Begin painting a new set of rocks. Now, you will end up with rocks of varying sizes. Some will be as small as your player, while others could be twice the size of the original mesh.

Editor Settings¶

The actions available in the tools palette give you absolute control of your forest placement. The first four tools allow you to adjust individual elements of your forest, such as a single tree. The Select Item tool allows you to select an individual element, which is indicated by a colored axis gizmo appearing on top of the item:

Once you have a tree selected, you can change its location without moving the entire forest. With the tree selected, activate the Move Item tool. The arrows gizmo will appear, allowing you to drag the tree around in the world. The Rotate tool, represented by a spherical gizmo, allows you to adjust the orientation of the tree in 3D space. You can use this to make individual trees lean in a specific direction. The Scale tool can be used to shrink or grow an individual tree. When you need to tidy up a forest, such as removing rogue trees, pressing the delete key when you have a tree selected will remove it from the scene.

If you need to delete entire sections of a forest, you may not want to delete each tree individually. Instead, you should use the Erase tool. The Erase tool is located directly below the Paint tool. When activated, the circle representing your brush in the world will turn from blue to red when you move your brush over the terrain:

Left click your mouse and drag the brush over a section of trees. Any trees under your brush will be removed from the forest object. This is much faster than deleting individual trees. If you want to remove a larger amount of trees such as clearing an area for a road, you can set the width of the brush to a specific width. Locate the Size dropdown on the Tool Settings bar and click on it. A slider will appear so you can increase the circumference of your brush. Set it to something fairly large, like 20.

Interface¶

To access the Mesh Road Editor press the F9 key or activate it from the main menu of the World Editor by selecting Editors>Mesh Road Editor. Alternatively you can click the Mesh Road icon from the World Editor Tool Selector Bar.

Whenever the Mesh Road Editor is active three sections of the screen are updated to contain the editors tool. On the right side of the screen are the Mesh Roads pane and the Properties pane. At the top is the Mesh Roads pane which contains a list of all the road meshes currently in the level, if any are present. At the bottom is the Properties Pane which displays the properties of the currently selected road mesh.

At the left of the screen the Mesh Road placement tools will appear and are used to create and modify road meshes. At the top of the screen in the World Editor Tool Settings bar, a new set of icons will appear. These icons and their associated values will enable you to quickly set up the width and depth of the control points and modify the editor to show and hide some visual aids which can be used to guide your road placement.

Adding a Mesh Road¶

A road mesh is created by placing a number of control points across the terrain. Each point can be edited for Road height, Road width and Road depth. By adjusting these points we have full control over how our road will look. The default width and depth of control points can be set using the Default Width and Default Height properties on the Tool Settings Bar at the top of the editor window. Any new road meshes will be created using these settings until you change their values again.

To create a new road mesh select the Create Road icon from the tool bar then click on the terrain with the left mouse button where you would like to start your road. Move the mouse away from the clicked location to see the results. Each time you click the terrain you will see three things:

1. a green square which represents the road location that you just placed
2. a blue square which represents the next location that will be placed the road if you press mouse button again
3. the surface of the road that will be placed the next time you click the button

Move the mouse to the next point on the terrain that you wish your road to travel to and then click again. Continue moving and clicking until you are finished with the initial placement of your road.

To complete the road placement process press the Esc key. This action will exit the Create Road tool leaving your new road selected and ready for adjustments.

To abort a road creation operation without placing a road at all press the Esc key before selecting a second road point. Once a second road point has been placed the only way to remove the road completely is to delete it, as explained later.

The new road will also show up in the Roads Mesh pane above the road Properties pane.

Editing a Mesh Road¶

The Road Mesh Editor provides several tools for modifying roads after they have been created. If at any time you make a mistake with any tool, you can press CTRL+Z to undo it.

Properties¶

The Properties pane on the right side of the screen can be used to configure a Mesh Road.

Mesh Road¶

The Mesh Road section contains properties which determine and control the textures used to display the Road Mesh. To change any of the textures for the Road mesh click the globe icon to its right. Clicking one of these icons you will open up the Material Selection window.

Click on the material you want to use for the road mesh property then click the Select button. The material will be entered in the propertys field and will be used as the material for that portion of the Road Mesh.

Top Material

Indicates the Material to use for the top surface of the road mesh.

Bottom Material

Indicates the Material to use for the underside surface of the road mesh.

Side Material

Indicates the Material to use for the sides of the road mesh.

Texture Length

Indicates the size in meters of the texture measured along the road center.

Break Angle

Indicates the angle in degrees that the mesh roads spline will be subdivided into if its curve becomes greater than this threshold.

Width Subdivisions

Subdivide segments width-wise this many times when generating vertices.

Interface¶

The Particle Editor can be activated from the dmain menu by selecting Editors -> Particle Editor. Or alternately, click the Particle Icon from the Tool Selector bar.Whenever the Particle Editor is active the Particle Editor – Emitters pane will be present on the right side of the screen. This pane is further divided into two tabs:

1. The Emitter tab contains properties about the currently selected emitter
2. The Particles tab contains properties about the currently selected particle.

Select either the Emitter tab or particle tab depending upon which object you wish to work with. In adition to the tabs there are also two buttons within the header of the Particle Editor.

Emitter Properties¶

The Emitter tab contains the properties that define an Emitter. Properties are grouped into sections:

Motion¶

These settings will affect the emitter spread pattern, speed, and particle image orientation:

Speed

The velocity the particle will leave the emitter in the defined spread pattern.

Speed Random

A random setting for varying the speed.

Orient to Movement Direction

Enabling this option fixes the particles image to the velocity direction of the particle. Note this will over ride any particle spin settings.

Align to a Direction

Enabling this option aligns the particles to a predefined vector set up in Align Direction option.

Align Direction

The vector used for particle alignment if the Align to a Direction option is checked.

Spread¶

These setting affect how the spread pattern will be dispersed:

Angle Min

The minimum angle for the emitter spread pattern.

Angle Max

The maximum angle for the emitter spread pattern.

Depth

The depth of the released pattern. A setting of 360 will create a spherical spread pattern when Angle Max is set to 360.

Offset

The distance from the emitter that particles will be released. Effectively the distance that the particle will be visible to the viewer.

Blending¶

These setting affect how the particle(s) are rendered.

Blend Type

The types of blending available to be applied to the particles.

Softness Distance

The particle edge blending distance. Removes the hard edges where the particle meets an object.

Ambient Factor

Adjusts the alpha blend (level of the particles which affects how transparent they are).

Sort Particles

The order in which particles are rendered.

Reverse Order

When enabled, reverses the render order set in the Sort Particles setting

Particle Properties¶

The Particle tab contains the properties that define a Particle. Properties are grouped into sections:

Interface¶

To access the River Editor you can either activate it from the main menu by selecting Editors > River Editor. Alternatively you can click the River icon from the World Editor Tools Selector Bar.

The editor has two main parts, one where you can add and manipulate the river nodes (control points) for creation, the other for adjusting the river properties to create the river style (depth, width, flow, ripples etc). Whenever the River Editor is active three sections of the screen are updated to contain the editors tool. On the right side of the screen are three panes. At the top is the Rivers pane which contains a list of all the rivers currently in the level, if any are present. In the middle is the River Nodes pane which displays the properties of the currently selected river control point. At the bottom is the Properties Pane which displays the properties of the currently selected river. At the left of the screen the River placement tools will appear and are used to create and modify rivers and their control points. At the top of the screen in the World Editor Tool Settings Bar, a new set of icons will appear when the River Editor is active. These icons and their associated values will enable you to quickly set up the width and depth of the river and modify the editor to show and hide some visual aids which can be used to guide your river placement.

Adding a River¶

The river is created by placing a series of control points across the terrain which defines the path you would like your river to follow. Each control point, also called a “node”, will give you control of how the river will look at any given point. By adjusting each of these points we can have full control of where our river will go, its size, and its orientation.

The default width and depth of control points can be set using the Default Width and Default Height properties on the Tool Settings Bar at the top of the editor window. Any new rivers will be created using these settings until you change their values again.

To create a new river select the Create River icon from the tool bar then click on the terrain with the left mouse button where you would like to start your river. Move the mouse away from the clicked location to see the results. Each time you click the terrain you will see three things:

1. a green square which represents the river location that you just placed
2. a blue square which represents the next location that will be placed the river if you press mouse button again
3. the surface of the river that will be placed the next time you click the button

Move the mouse to the next point on the terrain that you wish your river to travel to and then click again. Continue moving and clicking until you are finished with the initial placement of your river.

To complete the river placement process press the Esc key. This action will exit the Create River tool leaving your new river selected and ready for adjustments.

To abort a river creation operation without placing a river at all press the Esc key before selecting a second river point. Once a second river point has been placed the only way to remove the river completely is to delete it, as explained later.

The new River will also show up in the Rivers list at the right top of the screen. You will notice that the river itself is color-coded. These visual aids will be of help in adjusting your river.

RED

The red lines at the edges of the river represent the river bounds. These lines need to be moved so that they are hidden by the terrain river bank to avoid gaps between the edge of the water and the surrounding terrain.

GREEN

The green surface represents the depth of the river. This surface needs to be adjusted to be just below the terrain at every point in order for underwater views to be correct. Whenever this surface is above the terrain it will cause an “air bubble” between the bottom of the water and the terrain.

The new River may not look correct but with the following set of tools you will be able to adjust the width, depth and path.

Editing a River¶

The River Editor provides several tools for modifying rivers after they have been created. If at any time you make a mistake with any tool, you can press CTRL+Z to undo it.

Scaling a River¶

The width and depth of a river can be directly adjusted at a selected control point by using the Scale Point tool. To activate the Scale Point tool click on its icon on the Tool Selector. The scaling gizmo will appear.

Left mouse click on the colored cube at the end of any axis then drag the mouse while holding the button down to increase or decrease the size of the road along that axis. To adjust the width and depth at the same time left mouse click on the colored cube at the origin of the axes then drag the mouse while holding down the button. Release the mouse button to change the river to that new width and depth. Changing the width and depth of the river in this manner is the main method to make sure that the red edges and the green surface, mentioned above, are concealed by the terrain.

The Scale point tool will allow you to quickly create very wide river sections, even as wide as a small lake, without having to use a WaterBlock.

Properties¶

The Properties pane on the right side of the screen can be used to configure or modify various facets of the river object, such as its flow, colors, underwater effects, etc.

Water Object¶

This section contains properties that control the look and action of the water and contains several sub-sections.

Density

Affects the buoyancy of an object entering the water.

Viscosity

Affects a submerged object’s drag force.

Liquid Type

Type of datablock used to represent the type of liquid contained in the river (i.e. water, lava, etc.)

Base Color

Changes the color of the underwater fog which has the effect of coloring the water surface.

Fresnel Bias

Extent of Fresnel (reflection level based on viewing angle) affecting reflection fogging

Fresnel Power

Measures the intensity of the effect on the reflection, based on fogging.

Specular Power

Power used for secularity (lighting reflection) on the water surface (sun only)

Specular Color

Specular color used for the water surface ( sun only )

Underwater Fogging¶

This section contains properties that control how the underwater view appears.

Water Fog Density

The intensity of the underwater fogging.

Water Fog Density Offset

The offset distance before the fogging occurs.

Wet Depth

The depth in world units at which full darkening will occur, giving a wet look to objects underwater.

Wet Darkening

The refract color intensity scaled to the depth of the player (wetDepth). The deeper under the water you go, the darker it will get.

Distortion¶

This section contains properties that control how the water distorts the under water terrain when viewed from above.

Distort Start Dist

Determines the start of the distortion effect from the camera.

Distort End Dist

Max Distance that the distortion algorithm is performed. Lower values will show more of the distortion effect.

Distort Full Depth

Sets the scaling down value for the distortion in shallow water. The lower the value the more the distortion will be applied to the shallow area.

Interface¶

To access the Road and Path Editor activate it from the main menu of the World Editor by selecting Editors > Road and Path Editor. Alternatively, you can click the Road and Path icon from the World Editor Tool Selector Bar.

Whenever the Road and Path Editor is active three sections of the screen are updated to contain the editors tools. On the right side of the screen are the Roads and Paths pane and the Properties pane. At the top is the Roads and Paths pane which contains a list of all the decal-based roads currently in the level, if any are present. At the bottom is the Properties Pane which displays the properties of the currently selected road. At the left of the screen the Road and Path placement tools will appear which are used to create and modify your roads. At the top of the screen in the world editor tool bar, a new set of icons will appear after selecting the Road Editor. These icons and their associated values will enable you to quickly set up the width of the control points and modify the editor to show and hide some visual aids which can be used to guide your road placement.

There is no depth parameter for decal-roads as there is for Mesh based Roads. As mentioned earlier decal-based roads sit right on the terrain surface and follow the terrain exactly. They do not have their own geometry.

Adding a Decal Road¶

A decal-based road is created by placing a number of control points across the terrain. Each point can be edited for width at any time. By adjusting these points we have full control over how our road will look. The default width of control points can be set using the Default Width property on the Tool Settings Bar at the top of the editor window. Any new roads will be created using these settings until you change their values again.

To create a new road select the Create Road icon from the tool bar then click on the terrain with the left mouse button where you would like to start your road. Move the mouse away from the clicked location to see the results. Each time you click the terrain you will see three things:

1. a green square which represents the road location that you just placed
2. a blue square which represents the next location that the road will be if you press mouse button again
3. the road decals that were just placed

Depending upon the power of your computer there may be a delay between when you click the terrain and when the decals appear. Move the mouse to the next point on the terrain that you wish your road to travel to and then click again. Continue moving and clicking until you are finished with the initial placement of your road.

To complete the road placement process press the Esc key. This action will exit the Create Road tool leaving your new road selected and ready for adjustments.

To abort a road creation operation without placing a road at all press the Esc key before selecting a second road point. Once a second road point has been placed the only way to remove the road completely is to delete it, as explained later.

Editing a Decal Road¶

The Road and Path Editor provides several tools for modifying roads after they have been created. If at any time you make a mistake with any tool, you can press CTRL+Z to undo it. As with road placement, depending upon the power of your computer there may be a delay between when you perform and editing action and when the change appears in the scene.

Properties¶

The Properties pane on the right side of the screen can be used to configure a decal-based Road.

Decal Road¶

This section contains properties that control the roads appearance.

Material

The texture assigned to this property will be used as the decal that displays on the terrain to represent the roads surface. Clicking the small round icon to it right will open the Torque 3D Material Selector window. From this window you can select a new material to assign to the Material property. For full details on how to use the Material Selector and how to create new materials see the Material Editor article.

Texture Length

The length the texture will be rendered at in meters, measured along the centerline of the road.

Break Angle

Indicates the angle in degrees that the mesh roads spline will be subdivided into if its curve becomes greater than this threshold.

Render Priority

Decal roads are rendered in descending order.

Interface¶

The Shape Editor can be activated from the main menu by selecting Editors > Shape Editor.

The Shape Editor interface consists of five primary sections whenever it is active.

Shape Selector

The Shape Selector panel is used to choose a shape file for viewing and editing. It is composed of 3 tabs: Scene, Library and Hints. The Scene tab allows you to select a shape that has been placed in the current level. The Library tab allows you to browse and select any DTS or COLLADA shape from your project’s art folder. Finally, the Hints tab displays information about which nodes and sequences are expected by Torque for a given type of shape object.

Shape View Window

The main window shows a 3D view of the selected shape, and includes animation playback controls to play and single-step the selected sequence.

Properties Window

The Properties panel is used to view and edit the sequences, nodes, details and materials in the shape.

Advanced Properties Window

The Advanced Properties window displays Level-of-Detail information, and provides the ability to mount objects to other objects and animation thread control.

Toolbar and Palette

The Shape Editor adds several buttons to the standard World Editor toolbar to control the 3D shape view, and uses the familiar select/move/rotate palette for node transform manipulation.

Shape Selection¶

To start using the Shape Editor, first you need to select a shape. There are three ways to do this:

1. Select an object in the World Editor, then activate the Shape Editor from the menu bar or the toolbar. If the object uses a DTS or COLLADA file, it will automatically be selected in the Shape Editor.
2. Select an object using the Scene tree in the Shape Editor. This view is the same as that used in the World Editor, and provides a convenient way to select objects that have already been placed in the level. Note that the Shape Editor only allows selection of objects that use DTS or COLLADA files; selection of Interior or ConvexShape objects will be ignored.
3. Select a shape file using the Library tab. This view is the same as that used in the World Editor Meshes tab, and allows you to browse the DTS and COLLADA assets in your project’s art folder. This method allows you to view and edit shape files that have not yet been placed in the level.

The Force DAE option checkbox at the top of the Shapes panel forces Torque to load the COLLADA file, even if an up-to-date cached.dts file is present. Note that if the model is already present in the scene (and thus already loaded into the Torque Resource Manager), the Force DAE option will have no effect, as the shape will be opened from memory instead of from disk. This option is also available in the Editor Settings panel when working in the World Editor.

You will be prompted to save if there are unsaved changes in the current shape when a new shape is selected. The selected shape will appear in the View window, and listings of its sequences, nodes and materials will be displayed in the Properties window.

Shape Hints¶

The Hints tab in the Shape Selection window shows you which nodes and sequences are required for a particular type of shape to work with Torque.

Simply select the desired object type from the dropdown menu and the list of required nodes and sequences will be displayed underneath. Items that are present in the selected shape will be marked with a tick mark. Hovering the mouse cursor over an item will display a short description of the item. Double-click the item to add it to the current shape.

Most items are optional - the shape will still load and run without a particular node or sequence, but the object may not perform correctly in-game. A Player object for example uses a node called cam as the 3rd person camera position. If this node does not exist, the shape origin is used instead, which will probably not be correct for most character shapes.

It is easy to extend the Shape Editor hints for custom object types by adding to the list in: tools/shapeEditor/scripts/shapeEditorHints.ed.cs.

Shape View¶

The Shape View window displays the shape as it would be seen in-game, and also provides helpful rendering modes such as transparent, wireframe and visible nodes.

The camera can be rotated by dragging the right mouse button, translated by dragging the middle mouse button (drag left+right buttons if your mouse does not have a middle button), and zoomed using the mouse wheel. Use the Camera->View menu (or the dropdown list in the bottom right corner) to switch between the Standard/Perspective view and the orthographic views (Top, Bottom, Left, Right, Front, Back).

Hovering the mouse over a shape node will display the node name, and left clicking a node in the view will select it in the Node Properties panel (and vice versa). Once a node is selected, its transform can be modified by dragging the 3D gizmo similar to how objects are positioned in the World Editor.

Animation Controls¶

At the bottom of the Shape View window are the animation playback controls:

As well as allowing the selected sequence to be scrubbed with the slider, stepped one frame at a time, or played normally, the start and end frames of the sequence can be easily modified to facilitate sequence splitting or to correct off-by-one-frame looping errors. Sequence triggers appear as thin, vertical bars at the appropriate frame (as shown in the image above).

Pressing the in or out button, or modifying the text box directly (remember to hit Return to apply the change), will set the start or end frame of the sequence to the current slider position.

Properties Window¶

The Properties window is where you can view and edit the sequences, nodes, detail levels and materials in the shape. The top right corner has three buttons, which do the following:

• Save the shape
• Add a new sequence, node or detail; and
• Delete the selected sequence, node or detail

Nodes Tab¶

The nodes tab shows the node hierarchy and various properties of the selected node. The node properties available to view and edit are:

Name

The name of the node. To rename, simply edit the value and press Enter.

Parent

The parent of the node in the hierarchy. A new parent can be selected from the dropdown menu if desired.

Transform

The position and orientation of the node. Node transforms can be edited in either World mode (where the transform is relative to the shape origin), or Object mode (where the transform is relative to the node’s parent). Node transforms can also be edited visually in the Shape View window by selecting the node and dragging the axis gizmo, similar to how object transforms are edited in the World Editor. In World mode, the gizmo uses the global X,Y,Z axes, while in Object mode, the gizmo uses the node relative X,Y,Z axes (useful for seeing which way the node points for eye or cam nodes)

Editing Nodes¶

The Shape Editor allows shape nodes to be added, moved, renamed and deleted.

To add a node, simply press the New Node button in the top right corner of the Properties panel. If a node is currently selected, it will automatically be used as the initial parent for the new node. A new parent node can be selected using the dropdown menu. Renaming the node is as simple as typing a new name in the edit box and pressing Enter to apply the change.

There are two ways to edit node transforms: The first way is to manually edit the position and rotation values in the Node Property panel. This method is most useful when trying to set an explicit value. For example, you may require that a node be offset by exactly 2 units in the X direction from its parent node. Node transforms can be specified as either relative-to-parent (Object mode) or relative-to-origin (World mode).

The second way to edit node transforms is in the 3D Shape View. Simply select the desired node in the 3D view or in the node tree then drag the axis gizmo to the correct position and orientation.

It should be noted that the Shape Editor tool is not intended as a replacement for a fully-functional 3D modeling application, and as such, it only allows the non-animated transforms of the shape nodes to be edited. That is, the node transforms when the shape is in the root pose. You cannot use the Shape Editor tool to define new animation keyframes. For this reason, it is recommended to edit node transforms only when the <rootpose is selected in the Sequence Properties list. Node transforms can be edited when any sequence is selected, but the results may not be as expected, since animated parent nodes will affect the node transform as seen in the Shape View.

To delete a node, simply select it in the 3D Shape View or the node tree and press the Delete button in the top right corner of the Properties panel. Note that deleting a node will also delete all of its children.

+-base01
        +-start01
            +-Torso                   Object Torso with details: 2
            +-Head                    Object Head with details: 2
            +-LeftArm                 Object LeftArm with details: 2
            +-RightArm                Object RightArm with details: 2
            +-LeftLeg                 Object LeftLeg with details: 2
            +-RightLeg                Object RightLeg with details: 2

+-base01
  +-start01
    +-Truck                   Object Truck with details: 400 200 60
    +-Collision               Object Collision with details: -1

Advanced Properties Window¶

The Advanced Properties Window allows you to further change the settings of the model loaded in the shape editor.

Collision Tab¶

The Shape Editor can auto-fit geometry to a part or the whole of the shape for use in collision checking. Each time the settings are changed, the geometry in detail size -1 is replaced with the new auto-fit geometry. The node Col-1 (and any child nodes) may also be modified.

Fit Type

The type of mesh to auto-fit for this collision detail (see table below for details).

Fit Target

The geometry used to generate the auto-fit mesh. The target is either ‘Bounds’ (fit to the whole shape) or one of the shape sub-objects.

Max Depth

For convex hull auto-fit meshes, this specifies the maximum decomposition recursion depth. Increase this value to increase the number of potential hulls generated.

Merge %

For convex hull auto-fit meshes, this specifies the volume percentage used to merge hulls together. Increase this value to make merging less likely, and thus increase the number of final hulls.

Concavity %

For convex hull auto-fit meshes, this specifies the volume percentage used to detect concavity. Decrease this value to be more sensitive to concavity (and thus more likely to split a mesh).

Max Verts

For convex hull auto-fit meshes, this specifies the maximum number of vertices per hull. Increase this value to produce more complex (and CPU expensive) hulls.

Box %

For convex hull auto-fit meshes, this specifies the maximum volume error below which a hull may be converted to a box. Increase this value to allow more hulls to be converted to boxes.

Sphere %

For convex hull auto-fit meshes, this specifies the maximum volume error below which a hull may be converted to a sphere. Increase this value to allow more hulls to be converted to spheres.

Capsule %

For convex hull auto-fit meshes, this specifies the maximum volume error below which a hull may be converted to a capsule. Increase this value to allow more hulls to be converted to capsules.

Update Hulls

Re-compute convex hulls using the current parameters.

Revert Changes

Revert convex hull parameters to the values used for the most recent hull update.

The following types of geometry can be generated. The Box, Sphere and Capsule types are generally the most CPU efficient, and are converted to true collision primitives when the shape is loaded. The other types are treated as convex triangular meshes - the more triangles, the more expensive it is to test for collision against the mesh.

Type	Desciption
Box	Minimum extent object aligned box
Sphere	Minimum radius sphere that encloses the target
Capsule	Minimum radius/height capsule that encloses the target
10-DOP	Axis-aligned box with four edges bevelled; you can choose X, Y or Z aligned edges
18-DOP	Axis-aligned box with all edges bevelled
26-DOP	Axis-aligned box with all edges and corners bevelled
Convex Hull	Set of convex hulls

The k-DOP (K Discrete Oriented Polytope) types push ‘k’ axis-aligned planes as close to the mesh as possible, then form a convex hull from the resulting points as shown below.

The Convex Hull fit type performs a convex decomposition of the target geometry to generate a set of convex hulls. The basic algorithm is described here. For each hull that is produced, the hull volume is compared to the volume of a box, sphere and capsule that would enclose the hull. The hull is replaced with the primitive type that is closest in volume to the hull with volume % difference less than Box, Sphere or Capsule % respectively. If none of the primitive volumes are less than their respective error setting, the hull will be retained as a triangular mesh.

Shape Editor Settings¶

The Shape Editor settings dialog can be accessed from the main menu by selecting Edit Editor Settings, and allows the appearance of the editor to be customized. These settings are persistent and will be automatically saved and restored between sessions.

Saving Changes¶

The Shape Editor does not modify the DTS or COLLADA asset file directly. Instead, changes made in the editor are saved to a TSShapeConstructor object in a separate TorqueScript file. This file is automatically read by Torque before the asset is loaded, meaning you can safely re-export the DTS or COLLADA model without overwriting changes made in the Shape Editor tool. The change set will be re-applied to the shape when it is next loaded by Torque.

If needed, you can also re-edit the generated TSShapeConstructor object, either manually with a text editor, or by using the Shape Editor tool again.

To save changes to the current shape, simply press the save button in the top right corner of the Properties window. The script filename is the same as the DTS or COLLADA asset filename, only with a .cs extension. For example, saving changes to ForgeSoldier.dts would save to the file ForgeSoldier.cs in the same folder.

The Shape Editor TSShapeConstructor object may also be accessed directly from the console. For example:

• Dump the shape hierarchy to the console (handy for debugging shape issues):

  ShapeEditor.shape.dumpShape();
  

• Save the modified shape to DTS (instead of saving the change-set to a TSShapeConstructor script):

  ShapeEditor.shape.saveShape("myShape.dts");
  

• Set ground transform information (not yet available in Shape Editor UI):

  ShapeEditor.shape.setSequenceGroundSpeed("run", "0 4 0", "0 0 0");
  

Comments¶

The last rule is optional, but should be used as often as possible if you want to create clean code. Whenever you write code, you should try to use comments. Comments are a way for you to leave notes in code which are not compiled into the game. The compiler will essentially skip over these lines.

There are two different comment syntax styles. The first one uses the two slashes, //. This is used for single line comments:

// This comment line will be ignored
// This second line will also be ignored
%testVariable = 3;
// This third line will also be ignored

In the last example, the only line of code that will be executed has to do with %testVariable. If you need to comment large chunks of code, or leave a very detailed message, you can use the /*comment*/ syntax. The /* starts the commenting, the */ ends the commenting, and anything in between will be considered a comment:

/*
While attending school, an instructor taught a mantra I still use:

"Read. Read Code. Code."

Applying this to Torque 3D development is easy:

READ the documentation first.

READ CODE written by other Torque developers.

CODE your own prototypes based on what you have learned.
*/

As you can see, the comment makes full use of whitespace and multiple lines. While it is important to comment what the code does, you can also use this to temporarily remove unwanted code until a better solution is found:

// Why are you using multiple if statements. Why not use a switch$?
/*
if(%testVariable == "Mich")
  echo("User name: ", %testVariable);

if(%testVariable == "Heather")
  echo("User Name: ", %testVariable);

if(%testVariable == "Nikki")
  echo("User Name: ", %testVariable);
*/

Numbers¶

TorqueScript handles standard numeric types:

123     (Integer)
1.234   (floating point)
1234e-3 (scientific notation)
0xc001  (hexadecimal)

Strings¶

Text, such as names or phrases, are supported as strings. Numbers can also be stored in string format. Standard strings are stored in double-quotes:

"abcd"    (string)

Example:

$UserName = "Heather";

Strings with single quotes are called “tagged strings”:

'abcd'  (tagged string)

Tagged strings are special in that they contain string data, but also have a special numeric tag associated with them. Tagged strings are used for sending string data across a network. The value of a tagged string is only sent once, regardless of how many times you actually do the sending.

On subsequent sends, only the tag value is sent. Tagged values must be de-tagged when printing. You will not need to use a tagged string often unless you are in need of sending strings across a network often, like a chat system:

$a = 'This is a tagged string';
echo("  Tagged string: ", $a);
echo("Detagged string: ", detag($a));

The output will be similar to this:

Tagged string: 24
Detagged string:

The second echo will be blank unless the string has been passed to you over a network.

Booleans¶

Like most programming languages, TorqueScript also supports booleans. Boolean numbers have only two values- true or false:

true    (1)
false   (0)

Again, as in many programming languages the constant “true” evaluates to the number 1 in TorqueScript, and the constant “false” evaluates to the number zero. However, non-zero values are also considered true. Think of booleans as “on/off” switches, often used in conditional statements:

$lightsOn = true;

if($lightsOn)
  echo("Lights are turned on");

Arrays¶

Arrays are data structures used to store consecutive values of the same data type:

$TestArray[n]   (Single-dimension)
$TestArray[m,n] (Multidimensional)
$TestArray[m_n] (Multidimensional)

If you have a list of similar variables you wish to store together, try using an array to save time and create cleaner code. The syntax displayed above uses the letters n and m to represent where you will input the number of elements in an array. The following example shows code that could benefit from an array:

$firstUser = "Heather";
$secondUser = "Nikki";
$thirdUser = "Mich";

echo($firstUser);
echo($secondUser);
echo($thirdUser);

Instead of using a global variable for each user name, we can put those values into a single array:

$userNames[0] = "Heather";
$userNames[1] = "Nikki";
$userNames[2] = "Mich";

echo($userNames[0]);
echo($userNames[1]);
echo($userNames[2]);

Now, let’s break the code down. Like any other variable declaration, you can create an array by giving it a name and value:

$userNames[0] = "Heather";

What separates an array declaration from a standard variable is the use of brackets []. The number you put between the brackets is called the index. The index will access a specific element in an array, allowing you to view or manipulate the data. All the array values are stored in consecutive order.

If you were able to see an array on paper, it would look something like this:

[0] [1] [2]

In our example, the data looks like this:

["Heather"] ["Nikki"] ["Mich"]

Like other programming languages, the index is always a numerical value and the starting index is always 0. Just remember, index 0 is always the first element in an array. As you can see in the above example, we create the array by assigning the first index (0) a string value (“Heather”).

The next two lines continue filling out the array, progressing through the index consecutively:

$userNames[1] = "Nikki";
$userNames[2] = "Mich";

The second array element (index 1) is assigned a different string value (“Nikki”), as is the third (index 2). At this point, we still have a single array structure, but it is holding three separate values we can access. Excellent for organization.

The last section of code shows how you can access the data that has been stored in the array. Again, you use a numerical index to point to an element in the array. If you want to access the first element, use 0:

echo($userNames[0]);

In a later section, you will learn about looping structures that make using arrays a lot simpler. Before moving on, you should know that an array does not have to be a single, ordered list. TorqueScript also support multidimensional arrays.

An single-dimensional array contains a single row of values. A multidimensional array is essentially an array of arrays, which introduces columns as well. The following is a visual of what a multidimensional looks like with three rows and three columns:

[x] [x] [x]
[x] [x] [x]
[x] [x] [x]

Defining this kind of array in TorqueScript is simple. The following creates an array with 3 rows and 3 columns:

$testArray[0,0] = "a";
$testArray[0,1] = "b";
$testArray[0,2] = "c";

$testArray[1,0] = "d";
$testArray[1,1] = "e";
$testArray[1,2] = "f";

$testArray[2,0] = "g";
$testArray[2,1] = "h";
$testArray[2,2] = "i";

Notice that we are are now using two indices, both starting at 0 and stopping at 2. We can use these as coordinates to determine which array element we are accessing:

[0,0] [0,1] [0,2]
[1,0] [1,1] [1,2]
[2,0] [2,1] [2,2]

In our example, which progresses through the alphabet, you can visualize the data in the same way:

[a] [b] [c]
[d] [e] [f]
[g] [h] [i]

The first element [0,0] points to the letter ‘a’. The last element [2,2] points to the letter ‘i’.

Vectors¶

Vectors are a helpful data-type which are used throughout Torque 3D. For example, many fields in the World Editor take numeric values in sets of 3 or 4. These are stored as strings and interpreted as “vectors”:

"1.0 1.0 1.0"   (3 element vector)

The most common example of a vector would be a world position. Like most 3D coordinate systems, an object’s position is stored as (X Y Z). You can use a three element vector to hold this data:

%position = "25.0 32 42.5";

You can separate the values using spaces or tabs (both are acceptable whitespace). Another example is storing color data in a four element vector. The values that make up a color are “Red Blue Green Alpha,” which are all numbers. You can create a vector for color using hard numbers, or variables:

%firstColor = "100 100 100 255";
echo(%firstColor);

%red = 128;
%blue = 255;
%green = 64;
%alpha = 255;

%secondColor = %red SPC %blue SPC %green SPC %alpha;
echo(%secondColor);

Arithmetic Operators¶

These are your basic math ops.

Relational Operators¶

Used in comparing values and variables against each other.

Bitwise Operators¶

Used for comparing and shifting bits.

Assignment Operators¶

Used for setting the value of variables.

Note

The value of an assignment is the value being assigned, so $a = $b = $c is legal.

String Operators¶

There are special values you can use to concatenate strings and variables. Concatenation refers to the joining of multiple values into a single variable. The following is the basic syntax:

"string 1" operation "string 2"

You can use string operators similarly to how you use mathematical operators (=, +, -, *). You have four operators at your disposal:

Miscellaneous Operators¶

General programming operators.

if, else¶

This type of structure is used to test a condition, then perform certain actions if the condition passes or fails. You do not always have to use the full structure, but the following syntax shows the extent of the conditional:

if(<boolean expression>)
{
   pass logic
}
else
{
   alternative logic
}

Remember how boolean values work? Essentially, a bool can either be true (1) or false (0). The condition (boolean) is always typed into the parenthesis after the “if” syntax. Your logic will be typed within the brackets {}. The following example uses specific variable names and conditions to show how this can be used:

// Global variable that controls lighting
$lightsShouldBeOn = true;

// Check to see if lights should be on or off
if($lightsShouldBeOn)
{
   // True. Call turn on lights function
   turnOnLights();

   echo("Lights have been turned on");
}
else
{
   // False. Turn off the lights
   turnOffLights();

   echo("Lights have been turned off");
}

Brackets for single line statements are optional. If you are thinking about adding additional logic to the code, then you should use the brackets anyway. If you know you will only use one logic statement, you can use the following syntax:

// Global variable that controls lighting
$lightsShouldBeOn = true;

// Check to see if lights should be on or off
if($lightsShouldBeOn)
  turnOnLights();   // True. Call turn on lights function
else
  turnOffLights(); // False. Turn off the lights

switch, switch$¶

If your code is using several cascading if-then-else statements based on a single value, you might want to use a switch statement instead. Switch statements are easier to manage and read. There are two types of switch statements, based on data type: numeric (switch) and string (switch$):

switch(<numeric expression>)
{
   case value0:
       statements;
   case value1:
       statements;
   case value3:
       statements;
   default:
       statements;
}

As the above code demonstrates, start by declaring the switch statement by passing in a value to the switch(...) line. Inside of the brackets {}, you will list out all the possible cases that will execute based on what value being tested. It is wise to always use the default case, anticipating rogue values being passed in:

switch($ammoCount)
{
   case 0:
      echo("Out of ammo, time to reload");
      reloadWeapon();
   case 1:
      echo("Almost out of ammo, warn user");
      lowAmmoWarning();
   case 100:
      echo("Full ammo count");
      playFullAmmoSound();
   default:
      doNothing();
}

switch only properly evaluates numerical values. If you need a switch statement to handle a string value, you will want to use switch$. The switch$ syntax is similar to what you just learned:

switch$ (<string expression>)
{
   case "string value 0":
                statements;
   case "string value 1":
                statements;
   case "string value N":
                statements;
   default:
                statements;
}

Appending the $ sign to switch will immediately cause the parameter passed in to be parsed as a string. The following code applies this logic:

// Print out specialties
switch($userName)
{
   case "Heather":
      echo("Sniper");
   case "Nikki":
      echo("Demolition");
   case Mich:
      echo("Meat shield");
   default:
      echo("Unknown user");
}

for¶

As the name implies, this structure type is used to repeat logic in a loop based on an expression. The expression is usually a set of variables that increase by count, or a constant variable changed once a loop has hit a specific point:

for(expression0; expression1; expression2)
{
    statement(s);
}

One way to label the expressions in this syntax are (startExpression; testExpression; countExpression). Each expression is separated by a semi-colon:

for(%count = 0; %count < 3; %count++)
{
    echo(%count);
}

OUTPUT:
0
1
2

The first expression creates the local variable %count and initializing it to 0. In the second expression determines when to stop looping, which is when the %count is no longer less than 3. Finally, the third expression increases the count the loop relies on.

foreach¶

Simplify the iteration over sets of objects and string vectors. To loop over each object in a SimSet, use the foreach statement:

foreach( %obj in %set )
   /* do something with %obj */;

To loop over each element in a string vector, use the foreach$ statement:

foreach$( %str in "a b c" )
   /* do something with %str */;

while¶

A while loop is a much simpler looping structure compared to a for loop.

while(expression)
{
    statements;
}

As soon as the expression is met, the while loop will terminate:

%countLimit = 0;

while(%countLimit <= 5)
{
   echo("Still in loop");
   %count++;
}

echo("Loop was terminated");

Syntax¶

Even though objects are originally created in C++, they are exposed to script in a way that allows them to be declared using the following syntax:

%objectID = new ObjectType(Name : CopySource, arg0, ..., argn)
{
   <datablock = DatablockIdentifier;>

   [existing_field0 = InitialValue0;]
   ...
   [existing_fieldN = InitialValueN;]

   [dynamic_field0 = InitialValue0;]
   ...
   [dynamic_fieldN = InitialValueN;]
};

%objectID

Is the variable where the object’s handle will be stored.

new

Is a key word telling the engine to create an instance of the following ObjectType.

ObjectType

Is any class declared in the engine or in script that has been derived from SimObject or a subclass of SimObject. SimObject-derived objects are what we were calling “game world objects” above.

Name (optional)

Is any expression evaluating to a string, which will be used as the object’s name.

CopySource (optional)

The name of an object which is previously defined somewhere in script. Existing field values will be copied from CopySource to the new object being created. Any dynamic fields defined in CopySource will also be defined in the new object, and their values will be copied. Note: If CopySource is of a different ObjectType than the object being created, only CopySource’s dynamic fields will be copied.

arg0, ..., argn (optional)

Is a comma separated list of arguments to the class constructor (if it takes any).

datablock

Many objects (those derived from GameBase, or children of GameBase) require datablocks to initialize specific attributes of the new object. Datablocks are discussed below.

existing_fieldN

In addition to initializing values with a datablock, you may also initialize existing class members (fields) here. In order to modify a member of a C++-defined class, the member must be exposed to the Console.

dynamic_fieldN

Lastly, you may create new fields (which will exist only in Script) for your new object. These will show up as dynamic fields in the World Editor Inspector.

The main object variants you can create are SimObjects without a datablock, and game objects which require a datablock. The most basic SimObject can be created in a single line of code:

// Create a SimObject without any name, argument, or fields.
$exampleSimObject = new SimObject();

The $exampleSimObject variable now has access to all the properties and functions of a basic SimObject. Usually, when you are creating a SimObject you will want custom fields to define features:

// Create a SimObject with a custom field
$exampleSimObject = new SimObject()
{
   catchPhrase = "Hello world!";
};

As with the previous example, the above code creates a SimObject without a name which can be referenced by the global variable $exampleSimObject. This time, we have added a user defined field called “catchPhrase.” There is not a single stock Torque 3D object that has a field called “catchPhrase.” However, by adding this field to the SimObject it is now stored as long as that object exists.

The other game object variant mentioned previously involves the usage of datablocks. Datablocks contain static information used by a game object with a similar purpose. Datablocks are transmitted from a server to client, which means they cannot be modified while the game is running.

We will cover datablocks in more detail later, but the following syntax shows how to create a game object using a datablock:

// create a StaticShape using a datablock
datablock StaticShapeData(ceiling_fan)
{
   category = "Misc";
   shapeFile = "art/shapes/undercity/cfan.dts";
   isInvincible = true;
};

new StaticShape(CistFan)
{
   dataBlock = "ceiling_fan";
   position = "12.5693 35.5857 59.5747";
   rotation = "1 0 0 0";
   scale = "1 1 1";
};

Once you have learned about datablocks, the process is quite simple:

1. Create a datablock in script, or using the datablock editor
2. Add a shape to the scene from script or using the World Editor
3. Assign the new object a datablock

Handles vs Names¶

Every game object added to a level can be accessed by two parameters:

Handle

A unique numeric ID generated when the object is created

Name

This is an optional parameter given to an object when it is created. You can assign a name to an object from the World Editor, or do so in TorqueScript.

Example:

// In this example, CistFan is the name of the object
new StaticShape(CistFan)
{
   dataBlock = "ceiling_fan";
   position = "12.5693 35.5857 59.5747";
   rotation = "1 0 0 0";
   scale = "1 1 1";
};

While in the World Editor, you will not be allowed to assign the same name to multiple, separate objects. The editor will ignore the attempt. If you manually name two objects the same thing in script, the game will only load the first object and ignore the second.

Singletons¶

If you need a global script object with only a single instance, you can use the singleton keyword. Singletons, in TorqueScript, are mostly used for unique shaders, materials, and other client-side only objects.

For example, SSAO (screen space ambient occlusion) is a post-processing effect. The game will only ever need a single instance of the shader, but it needs to be globally accessible on the client. The declaration of the SSAO shader in TorqueScript can be shown below:

singleton ShaderData( SSAOShader )
{
   DXVertexShaderFile   = "shaders/common/postFx/postFxV.hlsl";
   DXPixelShaderFile    = "shaders/common/postFx/ssao/SSAO_P.hlsl";
   pixVersion = 3.0;
};

Fields¶

Objects instantiated via script may have data members, referred to as Fields.

Methods¶

In addition to the creation of stand-alone functions, TorqueScript allows you to create and call methods attached to objects. Some of the more important Console Methods are already written in C++, then exposed to script. You can call these methods by using the dot . notation:

objHandle.function_name();

objName.function_name();

Example:

new StaticShape(CistFan)
{
   dataBlock = "ceiling_fan";
   position = "12.5693 35.5857 59.5747";
   rotation = "1 0 0 0";
   scale = "1 1 1";
};

// Write all the objects methods to the console log
CistFan.dump();

// Get the ID of an object, using the object's name
$objID = CistFan.getID();

// Print the ID to the console
echo("Object ID: ", $objID);

// Get the object's position, using the object's handle
%position = $objID.getPosition();

// Print the position to the console
echo("Object Position: ", %position);

The above example shows how you can call an object’s method by using its name or a variable containing its handle (unique ID number). Additionally, TorqueScript supports the creation of methods that have no associated C++ counterpart:

// function - Is a keyword telling TorqueScript we are defining a new function.
// ClassName::- Is the class type this function is supposed to work with.
// function_name - Is the name of the function we are creating.
// ... - Is any number of additional arguments.
// statements - Your custom logic executed when function is called
// %this- Is a variable that will contain the handle of the 'calling object'.
// return val - The value the function will give back after it has completed. Optional.

function Classname::func_name(%this, [arg0],...,[argn])
{
   statements;
   [return val;]
}

At a minimum, Console Methods require that you pass them an object handle. You will often see the first argument named %this. People use this as a hint, but you can name it anything you want. As with Console Functions any number of additional arguments can be specified separated by commas.

As a simple example, let’s say there is an object called Samurai, derived from the Player class. It is likely that a specific appearance and play style will be given to the samurai, so custom ConsoleMethods can be written. Here is a sample:

function Samurai::sheatheSword(%this)
{
    echo("Katana sheathed");
}

When you add a Samurai object to your level via the World Editor, it will be given an ID. Let’s pretend the handle (ID number) is 1042. We can call its ConsoleMethod once it is defined, using the period syntax:

1042.sheatheSword();

OUTPUT: "Katana sheathed"

Notice that no parameters were passed into the function. The %this parameter is inherent, and the original function did not require any other parameters.