UnigineScript
The Language
Core Library
Engine Library
Node-Related Classes
GUI-Related Classes
Plugins Library
High-Level Systems
Samples
C++ API
API Reference
Integration Samples
Usage Examples
C++ Plugins
Content Creation
Materials
Unigine Material Library
Tutorials

Landscape Plugin

Landscape plugin allows to create any amount of terrains up to 16385 units in size. They are represented as a big terrain - landscape, split into the several small terrains of the declared size.

Each terrain is an independent separate object that has all the terrain features and can be modified in the same way. Besides, there is an opportunity of applying only the required tiles of the textures and masks right to the whole landscape or to any concrete grid cells of it.

This tool allows to create a big landscape without any restrictions in the size and apply all the necessary materials to it. All the textures will be automatically checked on the black sections and compressed into ZLC format for better memory optimization.

How to Load the Landscape Plugin

To start working with the Landscape plugin you need Unigine Editor to be running:

  • Open Tools -> Plugins and press Core button to see the list of the available editor plugins
  • Choose landscape/landscape.cpp file to load the plugin interface
  • Press Ok

Landscape plugin is now shown:

Landscape plugin interface

Landscape plugin interface

How to Create a New Landscape

During the new landscape creation only the Common tab of the Landscape plugin is active. You need to set all the main parameters for the new landscape, as some of them can't be changed after the landscape is created.

Terrain Parameters

A landscape is added with the following main parameters:

Terrain Step The size of a grid cell in units. Terrain Step determines how many times the terrain grid cell will be bigger than the default one (one unit).
Notice
Terrain Step parameter does not affect the storage size of the landscape; it just enlarges the terrain grid cell.
Size Specifies the size of the created square terrain grid cell in units. The size is defined as a power of two plus one. The minimum value is 513, the maximum - 16385.
Elevation The maximum possible height for the landscape relief in units. For detail information see the similar Height parameter for the terrains.
Size X
Size Y
Amount of the terrains to be created. Size X and Size Y determine how many terrains of the specified step and size will be created as a children of the landscape and how many of them will belong to X and Y axes respectively.
Storage
Width
Height
The final size of the landscape. Storage parameter shows the final size of the uncompressed/compressed landscape in bytes. Width and Height shows the summarized size of the Terrain Step, Size, Size X and Size Y parameters in units and refers to width and height of the terrain respectively. The values of this field change accordingly to the parameters changes.

Optimizing terrain rendering parameters (can be changed later):

Flatness The threshold to flatten polygons of the plains and flat terrain areas. The minimum value of 0 means the tessellation is uniform and non-optimized. The higher the value, the greater the height difference between the polygons is possible to render polygons as one large patch.
Lods Distance of the first level of details. The parameter specifies where distant-dependent tessellation starts.
Progression Progression of the level of details. Determines the level of details switching distance. The default value is 2. The lower the value, the faster the LODs are switched. The formula for progression: prev_distance + lod_distance * (lod_progression ^ number).
Visible Distance of the terrain visibility. Visible distance sets the range passing which the terrain is no longer rendered. Not the entire terrain disappears at once, but rather starting from the furthest surfaces. If set to infinity (inf), there is no distant-dependent optimization for the terrain.
Shadow Distance of terrain shadow. Allows to limit the distance up to which mountains, hills and other relief features of the terrain cast shadows (Surfaces -> Cast shadows and Cast world shadows should be enabled for this option to be in effect). The parameter is optional, by clicking the check box you can either enable or disable it. If set to infinity (inf), shadows will be casted across the whole visible terrain.
Radius Additional radius of the shadow. The parameter is active only when Shadow parameter is enabled.
Notice
You can read more about optimizing terrain rendering parameters in the Terrain Options article.

Textures sizes:

Diffuse Size
Coarse
Diffuse and diffuse coarse textures sizes per each terrain.
Normal Size
Coarse
Normal map and normal coarse texture sizes per each terrain.
Mask Size
Coarse
Mask and mask coarse textures sizes per each terrain.
Notice
If the coarse texture size is bigger than surface texture size, surface texture won't be created.
If the specified here and loaded surface texture sizes are not equal, the texture will be compressed/uncompressed automatically.

Textures pathnames:

Landscape Path The name of the landscape to be created. The folder with this name will be created under data directory and will contain all the terrains folders. The default name for the folder is landscape.
Terrain Name Name of the folder which refers to terrains. The default name is terrain. Each terrain will have it's own folder with a specific name. The folders will be created under data/landscape folder. The content of each folder:
  • terrain.ter terrain file
  • terrain_d.dds terrain diffuse texture file of the declared size which refers to landscape
  • terrain_n.dds terrain normal map file of the declared size which refers to landscape
  • terrain folder containing diffuse, normal and mask textures for all the terrains:
    • Diffuse texture files for each terrain of the declared size, default names are: 00x00_d.dds, 00x01_d.dds etc.
    • Normal map files for each terrain of the declared size, default names are: 00x00_n.dds, 00x01_n.dds etc.
    • Mask texture files for each terrain of the declared size, default names are: 00x00_m.dds, 00x01_m.dds etc.
Diffuse Name, Normal Name and Mask Name fields are the names of the respective textures mentioned above.
Notice
In the plugin system of notation, %xxx%xy default filenames consist of:
  • %xx and %xy - a hexadecimal numeration of the terrains, specify terrain coordinates along X and Y axes respectively; can also be a decimal numeration - %dx and %dy
  • Multiplication sign (x) between the numbers (splits the X and Y coordinates of the terrain)
This filenames can be changed.

Create a Landscape

After you have set all the parameters, press Create button to create a landscape.

To confirm the creation, click Yes when dialog window appears. A new empty landscape with the specified parameters is created. Now you can add and modify textures, detail materials and nodes for the landscape. Main parameters, texture sizes and textures pathnames can be no longer modified.

To switch between the terrains of the created landscape, go to the Nodes tab -> landscape node and choose required terrain inside the node.

File Structure of the Created Landscape

The whole file structure of the created landscape will look like:

  • data
    • landscape
      • terrain.ter
      • terrain_d.dds
      • terrain_n.dds
      • terrain
        • 00x00_d.dds
        • 00x00_m.dds
        • 00x00_n.dds
        • 00x01_d.dds
        • 00x01_m.dds
        • 00x01_n.dds
        • 10x00_d.dds
        • 10x00_m.dds
        • 10x00_n.dds
        • ...

Compress the Landscape

If all required modifications are made, press Compress button. The landscape will be compressed.

If you want to decompress your landscape, press Decompress button.

How to Load the Landscape

If you have already created settings configuration for the landscape, simply press Load button on the Landscape plugin interface panel, choose the directory to your .settings file and press Ok. When settings are loaded, you can either modify them or immediately create the new landscape with this settings.

How to Add the Detail Materials

After the landscape is created, Materials tab becomes active and can be modified.

Notice
To modify materials, make sure that the landscape node is chosen.

When creating a landscape, adding detail materials is done the same way as when creating the detail materials for the terrain.

The options are the same as for terrain except Clone button. It allows to make the copy of the settings configuration of the existed detail material for convenient editing of the another material with the similar settings.

How to Import the Textures

After the landscape is created, Import tab becomes active and can be modified.

Notice
To import textures, make sure that the landscape node is chosen.

Open Import tab in the Landscape plugin.

There are two modes of textures import: terrain based and source based. The difference between them is the following: Source based import allows to apply the concrete tiles of the specified texture to the whole landscape, while Source based import requires to specify either the texture tiles and the part of the landscape where this tiles will be applied.

Source Based Textures Import

This mode is the easiest-to-use and based on the source texture tiles usage. It means that we specify the tiles of the full source texture, which will be imported to the landscape (we don't need to specify the concrete part of the landscape, it will be counted automatically with regards to the texture tiles).

To start working in this mode, choose Source mode for both X and Y axes.

To import the texture or a part of it to the whole landscape, you should do the following:

  1. Specify the source texture (the number and the order of the source texture tiles along X and Y axes):
    Import X Import Y Import texture horizontal and vertical offset. Specifies the point on the source texture, from which the tiles along X and Y axes will be counted.
    Size X Size Y Import texture horizontal and vertical size. Specifies the amount of tiles along X and Y axes respectively counted relatively to the specified point (Import X, Import Y). As a result, there will be a rectangle made of tiles.
    Notice
    The terrain size will be adjusted in proportion to the source texture size. For example, if the terrain is of 32x32 grids and the source texture is of 64x64 tiles and you specify the full texture, the terrain will be divided into 64x64 grids for further tiles import.
  2. Specify the texture tiles you want to be imported to the landscape:

    Source X Source Y

    Source texture horizontal and vertical offset. Specifies the point on the source texture, from which the tiles along X and Y axes will be counted.

    Size X Size Y Source texture horizontal and vertical size. Specifies the amount of tiles along X and Y axes respectively counted relatively to the specified point (Source X, Source Y). As a result, there will be a rectangle made of tiles, which will be applied to the landscape.
  3. Specify textures paths:

    Checkboxes near every texture allows to choose the textures to be imported. You can enable all of them and import at the same time or enable just required ones.

    Height Path to the height data. Choose the folder with the height map.
    Diffuse Path to the diffuse data. Choose the folder with the diffuse texture.
    Normal Path to the normal data. Choose the folder with the normal map.
    Mask Path to the mask data. Choose the folder with the masks and choose the detail material to which the mask will be applied in the left drop-down menu.
    Notice
    The path to the folder with textures should be specified the same way as for filenames:
    • data/.../diffuse_x%xx_y%xy.png - hexadecimal designation
    • data/.../diffuse_x%dx_y%dy.png - decimal designation
  4. Import the selected textures:

    Flip Y Flips imported tiles of the textures around Y-axis.
    Clean Cleans the previous applied mask textures. If Clean parameter is not chosen, imported masks and existed ones will be blended.
    Notice
    A parameter is applied only for masks.
    Import Imports the data.

Source Based Textures Import Example

If your source texture is too big, you split it onto small parts. For example, the texture is rectangular and split onto 16 tiles per X axis and onto 8 tiles per Y axis. There will be 128 tiles.

If you want to apply the 4x4 square inside your texture to the landscape, you should do the following:

  1. First we will specify the texture size that will be used (any part of it then can be chosen and applied to the landscape). In our case we want to use the whole texture:

    • Choose Source mode for both X and Y axes.
    • Set 0 to both Import X and Import Y fields (we will count from the first tile, it's similar to the origin of coordinates)
    • Set 16 to Size X field and 8 to Size Y field (the whole 16x8 texture is involved for further adjustments)
  2. Then we set the offset and the size for the square that we want to import. Let it be the equidistant square in the horizontal and vertical:

    • Set 6 to Import X field and 2 to Import Y field (we choose the point on the texture from which the square will be applied)
    • Set 4 to Size X field and 4 to Size Y field (the square of side 4 will be applied to the landscape)
  3. Now lets deal with the textures. We want to import the diffuse texture and the mask for rocks for this square:

    • Enable Diffuse field and choose the path to the folder with diffuse textures
    • Enable Mask 0 field and choose the path to the folder with the mask for the rocks
    • Go to the left drop-down menu in the Mask 0 field and choose rocks (detail materials for the rocks should have been added)
    • Enable Flip Y field
    • Enable Clean field to erase previously applied masks if required
    • Press Import button

The square with the specified textures has been applied to the square inside the terrain.

Terrain Based Import

This mode is based on the landscape grid cells usage and can be implemented on 3 levels: terrains, surfaces and pixels (that work with terrain, surface and pixel entities respectively). We specify the texture part and the part of the landscape where the texture will be applied.

Choose Terrains/Surfaces/Pixels mode for both X and Y axes.

To import the texture or a part of it in the terrain based mode, you should do the following:

  1. Specify the whole landscape or a part of it, where you want the texture to be applied:
    Import X Import Y

    Import landscape horizontal and vertical offset. Specifies the point on the landscape, from which the grid cells along X and Y axes will be counted.

    Size X
    Size Y
    Import landscape horizontal and vertical size. Specifies the amount of landscape grid cells along X and Y axes respectively counted relatively to the specified point (Import X, Import Y). As a result, there will be a rectangle made of the landscape grid cells.
  2. Specify the texture tiles you want to be imported to the landscape:
    Source X
    Source Y

    Source texture horizontal and vertical offset. Specifies the point on the source texture, from which the tiles along X and Y axes will be counted.

    Size X
    Size Y
    Source texture horizontal and vertical size. Specifies the amount of tiles along X and Y axes respectively counted relatively to the specified point (Source X, Source Y). As a result, there will be a rectangle made of tiles, which will be imported to the landscape.

Another parameters are the same as for source based import.

How to Import the Nodes

After a landscape is created, Nodes tab becomes active and can be modified. This tab allows to import nodes with the fully applied mask or a part of it.

Notice
To import nodes, make sure that the landscape node is chosen.

There are two modes of the nodes import: terrain based and source based, which are similar to the textures import.

Source Based Nodes Import

This mode is the easiest-to-use and based on the nodes mask tiles usage. It means that we specify the tiles of the full source mask, which will be imported to the whole landscape (we don't need to specify the concrete part of the landscape, it will be counted automatically with regards to the texture tiles).

To start working in this mode, choose Source mode for both X and Y axes.

To import the node with the fully applied mask or a part of it, you should do the following:

  1. Specify the source mask (the number and the order of the mask tiles along X and Y axes):
    Import X
    Import Y

    Nodes mask horizontal and vertical offset. Specifies the point on the nodes full mask texture, from which the tiles along X and Y axes will be counted.

    Size X
    Size Y
    Nodes mask horizontal and vertical size. Specifies the amount of tiles along X and Y axes respectively counted relatively to the specified point (Import X, Import Y) of the mask texture. As a result, there will be a rectangle made of the mask tiles.
  2. Specify the mask tiles you want to be imported to the landscape:

    Source X
    Source Y

    Nodes mask horizontal and vertical offset. Specifies the point on the source mask, from which the tiles along X and Y axes will be counted.

    Size X
    Size Y
    Node mask horizontal and vertical size. Specifies the amount of tiles along X and Y axes respectively counted relatively to the specified point (Source X, Source Y) of the mask texture. As a result, there will be a rectangle made of tiles, which will be applied to the landscape.
  3. Add new nodes to the node list field:

    Checkboxes near the nodes field enable/disable all the nodes. You can enable/disable them separately by clicking the box near the Node field.

    Add Adds a new node.
    Clone Clones the selected node with all the parameters.
    Remove Removes the selected node.
  4. When the node is added and chosen, you can set the following parameters to it:

    Node A path to the node. Double click the field or press folder button at the right side to choose the path to the node file.
    Import Source mask path. Double click the field to choose the path to the node mask file.
    Notice
    The path to the folder with masks should be specified the same way as for filenames:
    • data/.../mask_x%xx_y%xy.png - hexadecimal designation
    • data/.../mask_x%dx_y%dy.png - decimal designation
    Mask Mask name pattern. A path is chosen relatively to the terrain directory.
    Size Mask size per terrain.
    Depth Node depth in the terrain children hierarchy.
    Format Mask format. R8, RG8, RGB8, RGBA8 formats are available.
    Combine Combines all nodes into the single node reference.
    Flip Y Flips imported tiles of the mask around Y-axis.
    Clean Cleans the previous applied mask textures. If Clean parameter is not chosen, imported masks and existed ones will be blended.
    Update Updates already existed nodes accordingly to made changes; nodes are not being recreated.
    Create Creates the nodes in accordance with all the set distribution parameters.

Terrain Based Nodes Import

This mode is based on the landscape grid cells usage. We specify the node mask part and the whole landscape or a grid cells of it where the texture will be imported.

Choose Terrains mode for both X and Y axes.

To import the texture or a part of it, you should do the following:

  1. Specify the whole landscape or a part of it, where you want the mask to be applied:
    Import X
    Import Y

    Import horizontal and vertical offset. Specifies the point on the landscape, from which the grid cells along X and Y axes will be counted.

    Size X
    Size Y
    Import horizontal and vertical size. Specifies the amount of landscape grid cells along X and Y axes respectively counted relatively to the specified point (Import X, Import Y). As a result, there will be a rectangle made of the landscape grid cells.
  2. Specify the mask tiles you want to be imported to the landscape:
    Source X
    Source Y

    Source node mask horizontal and vertical offset. Specifies the point on the mask texture, from which the tiles along X and Y axes will be counted.

    Size X
    Size Y
    Source node mask horizontal and vertical size. Specifies the amount of the mask tiles along X and Y axes respectively counted relatively to the specified point (Source X, Source Y). As a result, there will be a rectangle made of tiles, which will be imported to the landscape.

Another parameters are the same as for source based import.

Last update: 2017-07-03