Using Terragen with Atlas

One of the more frequently asked for features in the legacy terrain engine was support for importing data from landscape creation programs like Terragen. This section provides a brief walkthrough of how to import both heightmap and texture data from a terrain from Terragen.


Unfortunately, Terragen can only render a maximum 8129x8129 images without crashing. This means that it is a bit difficult to get high res terrain textures from it. Other programs may be better suited to this task.

Exporting A Heightfield

Exporting heightfield data from Terragen is a relatively straightforward affair. First, create a terrain of the desired size in Terragen. This is covered in the Terragen documentation, and won't be discussed here. Try googling for "Terragen Tutorial" or reading the manual that ships with the tool. :)

After creating the terrain, hit the Export... button and choose Raw 16-bits Intel Byte-Order. You will be prompted for a place to save the file. Choose the terrains directory in the demo (C:\torque\tgea\GameExamples\AtlasDemo\game\scriptsAndAssets\data\terrains if you used the default settings in the getting started guide) and save it.


It's useful to have a naming convention so that you can keep all your heightfields separate. One useful technique is to have the name, an underscore, the bit depth, another underscore, and the size of the heightfield. So you might have hill_16_4097.raw. This makes it easy to keep track of different files once you've collected a library of terrains.

Now that you've created a raw 16-bit heightfield, you need to generate a .chu chunk file for Atlas to load.

To do this, bring up TGEA. You will need to type a command into the console to generate the chunk file. Since this can take a while, and the command needs no setup or initialization to run, it might be convenient to simply place it as the last command in the root example/main.cs, followed by a call to quit();.

Here is an example call to generateChunkFileFromRaw16, which is what generates the chunk file:

    4096, 2.0, 1.0 / ( 2.0 * 2.0 * 2.0 * 2.0 * 2.0 * 2.0 * 2.0 * 1.5), 
    "demo/data/terrains/large.chu", 2.0, 6);

See the chunk file generation section for more information on the exact parameters. In short, though, this command will take demo/data/terrains/test_16_4097.raw and produce demo/data/terrains/large.chu from it.

Exporting A Texture

Terragen has a powerful rendering engine built into it. Although the results in detail can be a bit rough, it's still much easier to generate a texture than to hand-paint it!

Once you've prepared your surface parameters within Terragen, you can render a surface texture for use in Atlas. The first step, shown above, is to set up an orthographic projection by bringing up the render window, selecting camera settings, then hitting the Auto Setup button. This will automagically frame the terrain properly so that you will get pixels in all the right places.

The next step is to determine what size texture you want to generate. The shot above shows how to set this parameter. Hit the "Image Size" button and enter the size of texture you want for your terrain. Remember that the texture size must be a power of two and square.


By turning off features in the "Render Settings" window, you can speed up render times. Given that it takes about 12 hours to render an 8192 by 8192 texture on a 2Ghz+ machine, every little bit helps!

Ok! Now that you've gotten a good night's sleep and the render is done (remember, for testing you can always make a smaller 1024x1024 texture - it'll just be a lot blurrier looking), let's create a TQT from the texture.

You'll need to convert the .BMP generated by Terragen into a .JPEG. This is best done by using a tool like Photoshop - many image editors will choke on large images such as we'll be manipulating here. Also, the image produced by Terragen is probably going to be off by 90 degrees CCW. You'll want to correct that or the texture may look a bit odd in-engine.

Ok, so you have the texture in the textures subdirectory, just like you did with the .RAW in the previous section. Similarly to the previous section, you have to run a command to produce the .TQT file. This command is:

// Example of generating a TQT.
generateTQT("demo/data/terrains/TGEASurf.jpg", "demo/data/terrains/large.tqt", 5, 512);

This converts demo/data/terrains/TGEASurf.jpg into demo/data/terrains/large.tqt. The other two parameters control the way the texture is converted to a TQT.

The first parameter, 5, indicates the depth of the quadtree. This controls how many chunks the texture will be cut into for streaming. If it's more than the depth of the chunk file's quadtree, the lower levels of texture data won't get loaded!

The second parameter controls the size of the texture chunks in pixels. There's more info here, but the important thing is that 2depth times the chunk size needs to equal the size of the input image.

Putting Things In Game

Ok, you probably want to put these assets in game. Well, that's the simplest part of the whole process...

First, get your favorite text editor and open the mission (.mis) file.

Next, inside the MissionGroup SimGroup, add the following block:

   new AtlasInstance(BigChunk) {
      position = "0 0 0";
      rotation = "1 0 0 0";
      scale = "1 1 1";
      chunkFile = "~/data/terrains/large.chu"; // Don't forget to tweak these if
      tqtFile = "~/data/terrains/large.tqt";   // you named your files differently.


Currently, Atlas does not deal well with changing the chunk or TQT file settings in-engine. The best way to get things to work is to exit the game, edit the .mis, and reenter. A future milestone will resolve this issue.

Save the mission file, and you're all ready to go. Launch the mission and enjoy your new terrain!