Interface Overview
Assets Workflow
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Setting Up Development Environment
Usage Examples
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
Double Precision Coordinates
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
Rendering-Related Classes

Landscape Terrain

The Landscape Terrain system provides advanced simulation of terrain - the most important object in outdoor scene rendering. UNIGINE provides Object Landscape Terrain — the object that allows reconstructing practically any arbitrary landscape with diverse features:

  • Virtually infinite terrain surface
  • Extreme details up to 1 mm per pixel
  • Adaptive hardware tesselation with displacement mapping
  • Dynamic modification at run time - craters, funnels, trenches
  • Simple and clear API
  • Up to 1024 detail materials
  • Layers system with flexible blending rules
  • Binoculars/scopes support (x20 / down to 1-degree FOV)
  • Optimized rendering and physics performance
  • Support for simultaneous editing by a team of 3D artists
  • Decal-based holes

The Landscape Terrain system is based on the principle of decomposing terrain graphic data that is too large to fit in the graphic memory in its entirety into smaller rectangular sections known as “tiles”. Asynchronous streaming of these tiles makes it possible to render only necessary data at a full level of detail regardless of the camera's field of view with multiple cameras supported. Flexible streaming settings make it possible to configure terrain rendering even for computers with a limited VRAM capacity.


To simulate overhangs and caves, use static meshes.
DirectX is the recommended graphic API for the Landscape Terrain system. If you are using OpenGL consider adjusting the render settings.

See Also#

Landscape Terrain Operation#

The Landscape terrain system is represented by two objects:

  • ObjectLandscapeTerrain is responsible for visualization only: this object renders geometry and textures. Also, it stores detail data.
  • LandscapeLayerMap objects store the data used for rendering (height, albedo, and detail masks) and represent terrain layers that can be arranged in the scene and blended with each other.
    The data stored in a LandscapeLayerMap is not intended for terrain only, it is designed as a shared data pool to be used by other objects as well, such as Grass, for example.

There can be several Landscape Terrain objects in the scene, but only one of them (active) shall be rendered.

Graphic data from Landscape Layer Maps and details (original full-size textures and generated mipmaps) are asynchronously streamed and transferred to the main mega-texture, based on which the Landscape Terrain is rendered. The mega-texture includes 3 terrain textures:

  • RGBA8 Albedo,
  • RGBA8 Normal,
  • R32F Height.

Output of the Render Textures helper. The Terrain section contains Landscape-related textures.


A scene may contain thousands of Landscape Layer Maps, so the graphic data of the Landscape terrain may be too large to fit in the video memory in its entirety. Instead all resources are decomposed into smaller rectangular sections — tiles. Individual tiles are asynchronously loaded into the main mega-texture when necessary — only if currently seen by the camera.

Some visual artifacts (wrong data or missing tiles) may appear during long run time of the application due to slight error accumulation of the hash function used to identify loaded tiles.

Use the render_show_terrain_streaming 1 console command to enable visualization of streaming of tiles. In this mode colored areas show the tiles that are currently being rendered in a lower resolution until the highest MIP-level is loaded.

Streaming of tiles

Streaming is based on using previously loaded geometry to define the visible areas of terrain. The Culling option enables uploading preliminary low-level data of a Landscape Layer Map to CPU (about 2 meters per pixel) to be used for checking what tiles are to be streamed next. For maps with the Culling option disabled, only high-detail data of the base map is uploaded on CPU. Disable this flag for landscape layer maps that contain high-detail graphic data and are used as insets (placed within the bounds of another layer map for higher level of detail) to exclude them from loading preliminary low-level data and reduce load on CPU. The render_terrain_culling_* console parameters are used for fine tuning.

Control the number of loaded tiles per each frame via the render_terrain_tiles_load_per_frame console parameter.

Loaded tiles are cached into RAM and VRAM for better performance, if the cache memory limits are reached newer tiles replace the older ones. The CPU cache is crucial for intersection detection, collisions and streaming. You can set the CPU and GPU cache memory limits in percentage of the total RAM/video memory by using the corresponding render_terrain_cpu_cache_size and render_terrain_gpu_cache_size console commands.

It's highly recommended not to set the highest possible cache memory limits as it may be slightly exceeded during run time.

The render_terrain_gpu_cache_life_time and render_terrain_gpu_cache_update_limit console parameters let you set up the lifetime for each cached tile in number of frames and the maximum cache validation time in milliseconds.

If you modify a layer map by using Brush Editor or your project implies run-time terrain modification, increase the cache memory limits and lifetime for better performance.

Blending of Layers#

When overlapping each other Landscape Layer Maps are blended per channel providing convenient development workflow. The following blending modes can be set for each map of a Landscape Layer Map separately:

  • Additive — data of the layer map is added atop.
  • Alpha-Blend — the colors of this layer map and the underlaying one are blended.
  • Overlay — added data replaces the data below it.
  • Miltiplicative — the albedo colors are multiplied.
The order of blended layers matters, use the higher Order value for layer maps that should be on top.
The height channel supports only Additive and Alpha-Blend modes.

Layer maps can vary in density and size, so it is easy to create insets of different quality and modify the terrain surface at run time.

Collaborative Editing#

Blending of separate layer maps makes the Landscape terrain system friendly for collaborative editing. A team of 3D artists can design separate layer maps simultaneously and develop a large landscape piece by piece without conflicts.

In addition to other UNIGINE features for cooperative development (e.g. Layer, Node Reference), different parts of scenes of virtually any complexity can be developed simultaneously by multiple artists.

Run-time Modification#

Vehicles leaving tracks while moving or even an excavator digging trenches are easy to model. Real-time terrain CPU- or GPU-based modification via API is as simple as 1, 2, 3:

  1. Copy a part of terrain data for a certain area to a buffer
  2. Modify the buffer as you want (height, color, masks, or all of them at once)
  3. Paste the buffer back to the terrain replacing old data.
For more details on performing run-time CPU- and GPU-based modification please refer to the Landscape class article.

Another simple way to modify terrain’s appearance is to create custom LandscapeLayerMap objects having their own height, albedo and masks data and adding them above existing ones.


ObjectLandscapeTerrain stores visual settings for 20 detail masks intended for reaching better level of visual quality in close up views. Details represent arbitrary albedo, roughness and height (displacement) data, so you can drastically improve the look of the landscape terrain. Details are rendered according to detail masks of LandscapeLayerMap objects.

If your project requires detection of collisions with the terrain surface, you should keep in mind that Details don't participate in Intersection and Collision Detection, so it's not recommended to apply intense displacement using details since visual inconsistency may appear.

Detail settings available in ObjectLandscapeTerrain parameters allow defining the detail visual appearance, adding up to 1024 details to a mask and defining the material of each detail.

Detail parameters are available on the Node tab of the ObjectLandscapeTerrain parameters.

The list of detail masks displays the hierarchy of details for each of 20 detail masks. Using buttons at the top you can:

  • create a detail for all selected masks.
  • clone the selected details.
  • move up the selected details.
  • move down the selected details.
  • delete the selected details
Drag details using the mouse to set up the hierarchy, Double-click on a detail or a detail mask to rename it.

Internally 20 detail masks are stored in 4 RGBA8 mask textures of each LandscapeLayerMap in the scene. The following parameters display the info on the corresponding texture mask:

Mask Texture The index of the mask texture used.
Channel The channel of the mask texture used.

Detail parameters allow applying additional masking:

Mask Threshold Threshold starting from which the mask starts to be rendered.
Mask Contrast Contrast of the mask.
Mask by Albedo Select a color of the albedo to be used as a mask. In this case, all areas on the terrain having selected color will be covered by the detail.
Mask by Height This group of parameters is used for mask modulation. For the areas specified by the mask, you can set up the range of heights in which the detail is visible.
  • Min Visibility — minimum height value starting from which the detail mask begins to fade in until it becomes completely visible. The default value is -inf.
  • Max Visibility — maximum height value starting from which the detail mask begins to fade out until it becomes completely invisible. The default value is inf.
  • Min Fade — over this height range below the minimum height value the detail mask will fade in until it is completely visible. The default value is 0.
  • Max Fade — over this height range above the maximum height value the detail mask will fade out until it is completely invisible. The default value is 0.
Enter the Detail Masks Debug mode using the render_show_terrain_mask N console command, where N is the index of a detail mask from 1 to 20.

The Detail Material section contains settings of the terrain_detail_base material assigned to the current detail.

Intersections and Collisions#

The Landscape Terrain system provides intersection and collision detection with the terrain surface the same way as for usual meshes. To enable collisions and/or intersection detection for a landscape:

  • Turn on the Collider Object flag on the Node tab.
  • Switch to the Surface tab and enable the Intersection and Collision flags, configure the bit masks.
  • For landscape layer maps that should take part in collisions and intersections enable the corresponding Collision and Intersection flags.
Details don't participate in Intersection and Collision Detection.

Intersections are detected with a variable precision, starting from a lower value and ending up with a higher one.

Normally there's no need to modify these values. In case of intersection detection errors you can open Landscape Terrain parameters and try tweaking start and end precision values and enable cubic filtering of textures for optimum balance, but be careful as it may significantly affect performance and accuracy:

Collision Bicubic Filter Enables bicubic filtering of textures for collision detection.
Intersection Bicubic Filter Normal Enables bicubic filtering of the normal texture for intersection detection.
Intersection Bicubic Filter Height Enables bicubic filtering of the height texture for intersection detection.
Intersection Precision Begin Starting precision of intersection detection.
Intersection Precision End Ending precision of intersection detection.

Creating a Terrain#

Creating a terrain in UnigineEditor:

  1. In the Create menu, select Landscape -> Landscape Terrain. Click in the Scene viewport to add the terrain.

    Landscape Terrain is created with a Landscape Layer Map as a child.
  2. Select the Landscape Layer Map in the hierarchy, its settings will be displayed in the Parameters window.
    The default Landscape Asset assigned to a new Landscape Layer Map is read-only, so you should create a new one to be able to modify it.
  3. Set the desired size and specify Height, Albedo, and Masks data for the Landscape Layer Map(s), or sculpt and paint your Landscape Layer Map from scratch using the Brush Editor.
  4. Select the Landscape Terrain object and set up necessary details.
  5. To add another layer (an inset), click Create -> Landscape -> Landscape Layer Map.
    You can move Landscape Layer Maps along X and Y axes and rotate them around the Z axis.
  6. If your Landscape Terrain object has multiple Landscape Layer Maps, adjust blending and rendering order for them, if necessary.
  7. Your terrain is ready. If any streaming artefacts appear, or performance and memory consumption adjustment is required, please configure rendering and streaming parameters for it.

Configuring Terrain Streaming#

The Landscape Terrain is a powerful system for landscape simulation featuring scopes/binoculars support, multiple cameras and run-time modification. Using these advantages may increase performance consumption really quickly.

Flexible streaming settings make it possible to configure terrain rendering even for computers with a limited VRAM capacity, but these settings depend on the content used (distances, level of detail, etc.) and requirements (the number of cameras and simultaneous viewports, etc.) and are to be set per project individually. When developing a Landscape Terrain pay attention to the following streaming settings:

  1. Adjust the render_terrain_texture_memory_size parameter so the size of all terrain render textures fits your VRAM and the terrain surface doesn't have noticeable flickering.
  2. Prepare all cameras in the project, open all viewports if your project requires more than one. Two cameras observing the same area of the terrain at the same time don't increase the resources consumption while cameras that visualize different parts of the landscape will require higher amount of detail.
  3. Check the performance and resources consumption using the Rendering Profiler tool and the Render Textures helper at the full screen size and resolution of the target platform.
  4. Adjust the cache memory limits and the render parameters to avoid visual artifacts, streaming errors and performance spikes.
    If you modify a layer map by using Brush Editor or your project implies run-time terrain modification, increase the GPU cache memory limit and lifetime for better performance.

Landscape Render Parameters#

ObjectLandscapeTerrain doesn't cast shadows and self-shadows from light sources. Only Screen-Space Shadows from light sources are supported at the moment.

The overall terrain detail level and stable work depend on a set of parameters. The size of the terrain textures defines the number of tiles presented in the video memory: the higher the value, the more tiles you can have loaded at a moment. This parameter has the highest effect on the amount of VRAM consumption and is defined by the render_terrain_texture_memory_size console parameter in the [0, 1] range, where:

  • 0 stands for the size of 3072×3072 pixels for each of 3 terrain textures (~140 MB of VRAM),
  • 1 stands for the size of 16384×16384 pixels for each of 3 terrain textures (~4 GB of VRAM).
Lower values require less video memory but can make the terrain surface flicker due to constant reloading of resources that replace each other.
The amount of VRAM used is also highly affected by the viewport resolution. Thus, when developing a project using a Landscape Terrain, you should check performance and memory consumption at the screen size of the target platform.

The render_terrain_density parameter varies from 0 to 10000 units and represents the maximum allowed density of the terrain, the default value of 1000 corresponds to the density of 1 mm.

The geometry of the landscape terrain is split down to a fixed number of levels of detail (21) and rendered using hardware tesselation. The quality of tesselation is controlled by the geometry parameters, such as the Subpixel Reduction, Displacement Progression and strength of LODs fading. Control the density of generated geometry separately using the render_terrain_geometry_density console parameter.

Resolutions of the detail albedo and height textures control the final quality of details. They're both set in the [0, 8] range:

  • 064×64 pixels for each detail texture,
  • 816384×16384 pixels for each detail texture.

During rasterization, the renderer selects the MIP-level of textures according to the angle of the surface to the camera: the surfaces that are not faced to the camera may be rendered at a lower quality. Control the detail level via the following console commands:

OpenGL Settings#

Though DirectX is the recommended graphic API for the Landscape Terrain system, OpenGL is also supported but has quite serious limitations: asynchronous operations are not available regarding the Landscape Terrain system. Additional setup may be required in order to achieve even acceptable performance. Consider following these suggestions:

gl_terrain_use_async 0 Disable asynchronous data loading to get rid of spikes at the cost of the loading speed.
gl_terrain_waiting_frames Number of frames to wait for streaming. Increase this value (4-16 frames) to avoid more performance spikes and slightly improve the loading speed by forcing deferred data loading that imitates asynchronous data streaming without synchronization points.
render_terrain_cpu_cache_size Increase the memory limit of cache.
render_terrain_gpu_cache_size Increase the memory limit of GPU cache.
render_terrain_gpu_cache_life_time Increase the lifetime of GPU cache. Keep noted that memory limits of cache may be exceeded in the case when the lifetime is highly increased.
render_terrain_tiles_load_per_frame Decrease the number of loaded tiles per frame to 1 to get rid of performance drops. Low values make streaming slower and more noticeable.
Last update: 2019-11-29