Creating a Torque X Terrain

In the Torque X Forums, I've seen a few questions come up about creating 3D terrain. Since it's not an easy process, I thought an easily searhable posting here would help.

The XTerrain Class

In Torque X, the XTerrain class supports the creation of three different types of terrains: a TGE legacy terrain, a chunked geometry terrain, and a procedurally generated terrain. All terrains use the XTerrain class. Each different terrain type is implemented by creating an instance of the TerrainData class and then attaching it to the Data property of the XTerrain class.

Regardless of which type of terrain you plan to create, you always need to start with the XTerrain class. The XTerrain class inherits from TorqueObject, so it must be registered with the TorqueObjectDatabase and can have components. In fact, the most important component attached to the XTerrain is the T3DRigidComponent, without which, everything would fall through the terrain.

Begin creating a terrain by getting a local reference to the scene’s rigid physics manager. Next, create the XTerrain object and set its public properties. Attach a T3DSceneComponent to the XTerrain to give it a presence within the 3D scene. The only other component needed is a T3DRigidComponent to process all other rigid physics reactions in the scene. This component needs a RigidMaterial to define the collision surface and a collision shape, provided by the CollisionXTerrainShape class. Lastly, specify a TerrainData object that contains the details about the terrain’s shape. All that remains is to register with the TorqueObjectDatabase.

public void CreateTerrain()
{
    //find the physics resolver
    RigidCollisionManager rigidManager =
        TorqueObjectDatabase.Instance.FindObject<RigidCollisionManager>("RigidManager");

    //create the terrain
    XTerrain objTerrain = new XTerrain();
    objTerrain.Name = "Terrain";
    objTerrain.HorizontalScale = 8;
    objTerrain.VerticalScale = 1;
    objTerrain.LevelZeroError = 0;
    objTerrain.ViewError = 2;
    objTerrain.LODLevels = 4;
    objTerrain.LODError = 0.5f;
    objTerrain.Repeat = true;
    objTerrain.Visible = true;

    //give the terrain presence in the scene
    T3DSceneComponent componentScene = new T3DSceneComponent();
    componentScene.Position = new Vector3(0, 0, 0);
    componentScene.SceneGroup = "Terrain";
    objTerrain.Components.AddComponent(componentScene);

    RigidMaterial materialRigid = new RigidMaterial();
    materialRigid.Restitution = 0f;
    materialRigid.KineticFriction = 1f;
    materialRigid.StaticFriction = 1f;

    //give the terrain some physics attributes
    T3DRigidComponent componentPhysics = new T3DRigidComponent();
    componentPhysics.SceneGroupName = "Terrain";
    componentPhysics.GravityScale = 0f;
    componentPhysics.RigidManager = rigidManager;
    componentPhysics.RigidMaterial = materialRigid;
    componentPhysics.Immovable = true;
    //componentPhysics.CollisionBody.AddCollisionShape(new CollisionXTerrainShape());
    objTerrain.Components.AddComponent(componentPhysics);

    // ------  SPECIFY A TERRAIN DATA TYPE  ------
    TGETerrainData terrainData = new TGETerrainData();
    terrainData.TerrainFilename = "data/terrains/terrain.ter";
    terrainData.LightMapFilename = "data/terrains/lightmap.png";
    terrainData.TexturePathSubstitution = "data/terrains";
    terrainData.DetailMaterial = "TerrainDetailMaterial";
    objTerrain.Data = terrainData;

    //register the terrain
    TorqueObjectDatabase.Instance.Register(objTerrain);
}

At this point, we still have an incomplete terrain object. We need to attach a TerrainData with one of the preferred data formats in order to have it appear within the scene. Typically, the terrain format you choose depends upon the toolset and function of the terrain.

Using Legacy Terrain Data

The legacy terrain data format dates back to the original Torque Game Engine and uses a heightmap to determine the terrain’s shape. The terrain data is stored in a .ter file and can really only be edited with the Torque Game Engine’s Terrain Editor. The purpose for including support for format is to facilitate the migration of games into the Torque X Framework.

To use the legacy terrain format, copy the following code fragment to the end of your CreateTerrain() method. This fragment creates an instance of the TGETerrainData class and specifies paths to the .ter terrain file and the lightmap texture file.

//specify terrain data
TGETerrainData terrainData = new TGETerrainData();
terrainData.TerrainFilename = "data/terrains/terrain.ter";
terrainData.LightMapFilename = "data/terrains/lightmap.png";
terrainData.TexturePathSubstitution = "data/terrains";
terrainData.DetailMaterial = "TerrainDetailMaterial";
objTerrain.Data = terrainData;

Keep in mind that there is no XNA content processor for the .ter file. After you add it to your game's content project, set the Build Action property to “Content” and Copy to output directory property to “Copy if newer” - do not set it to "Compile". The TGE terrains is great and flexible, but it is also small. It's best suited when you need terrain to decorate a 3D scene but not be fully explored since it will tile/repeat pretty quickly.

Using Raw Terrain Data

To use the Raw terrain format, copy the following code fragment to the end of your CreateTerrain method. This fragment creates an instance of the RAWTerrainData class and specifies a path to the .raw terrain file and the lightmap texture file.

RAWTerrainData terrainData = new RAWTerrainData();
terrainData.TerrainFilename = "data/terrains/l3dt_generated.raw";
terrainData.LightMapFilename = "data/terrains/l3dt_generated_LM.jpg";
terrainData.UniqueTextureFilename = "data/terrains/l3dt_generated_TX.jpg";
terrainData.DetailMaterial = "TerrainDetailMaterial";
objTerrain.Data = terrainData;

At present, the most popular tool for creating Atlas terrains is called Large 3D Terrain Creator, or L3DT for short, by Bundysoft. This reasonably priced software guides you through the creation of large RAW terrain files. When working with L3DT, keep try the following guidelines. Start by selecting File + New Project from the main menu and then selecting the Design/Inflate algorithm.

• Set a map size of 16 for the X and Y values
• Set the horizontal scale to 10
• Do not enable disk paging for mosaic maps
• Enable edge wrapping to produce a terrain that can be tiled
• Experiment with the remaining settings, such as elevations and climates
• You’ll need to create a Design map, Heightfield, Terrain normals, and a Light map

You can save the project and all maps directly to your game project’s data/terrains folder as “l3dt_generated”. Next, you can export the files that the RAWTerrainData class needs.

• Select File + Export + Export map...
• Select the Heightfield map
• Set the file format to Raw
• Browse to the data/terrains folder and set the file name to l3dt_generated.raw
• Do not resize the file by 1 or flip the heightmap as formerly done with TGEA

After the terrain maps have been exported, return to XNA Game Studio and add the “l3dt_generated.raw”, “l3dt_generated_LM.jpg”, and the “l3dt_generated_TX.jpg” files into your game project. Remember to set the properties for the.raw file. The Build Action property should be set to “Content” and Copy to output directory property should be set to “Copy if newer”.

Using Procedural Terrain Data

L3DT presents a colorful show as it produces all of the related terrain files. When it completes, you can browse through the collection of detailed texture maps.

The procedural terrain dynamically creates a terrain landscape at runtime based upon parameters you set in code. It’s a great solution for games that do not require a specific terrain shape because it renders quickly and does not need to include any extra terrain data files. This works well for a flight simulator, where you can see a terrain, but not really interact with it. However, it may not work well for land-based games, where the specific placement of ground structures is required.
To use the procedural terrain format, copy the following code fragment to the end of the CreateTerrain method. This fragment creates an instance of the GeneratedTerrainData class and specifies several computational properties as well as a lightmap texture file.

//specify terrain data
GeneratedTerrainData terrainData = new GeneratedTerrainData();
terrainData.Size = 1025;
terrainData.SmoothingPasses = 2;
terrainData.Jitter = 3;
terrainData.TerrainFilename = "data/terrains/terrain.ter";
terrainData.LightMapFilename = "data/terrains/lightmap.png";
terrainData.TexturePathSubstitution = "data/terrains";
objTerrain.Data = terrainData;

As you can see, there's a lot of flexibility when it comes to Torque X terrains. Although the toolset is still catching up, there's a lot you can do with code an external tools, such as L3DT and the TGE Terrain Editor.

One last item... a new update to Torque X 3.0 that applies fixes to the 2D builder is available, so be sure to download that if you're running into trouble with Tilemaps or Particle Effects.

John K.
www.envygames.com