14. Terrain

An AGX Terrain is a deformable height field along with a symmetric 3D grid data structure that is used to simulate earth moving operations. Special rigid bodies called Shovels are used to deform the Terrain and spawn Soil Particles. An AGX Dynamics for Unreal terrain is created from an Unreal Engine Landscape.

14.1. Creating a Terrain

14.1.1. Creatng a Landscape

The first step in creating a Terrain is to create an Unreal Landscape. There is a one-to-one correspondence between Landscape quads and Terrain cell columns in the 3D grid.

Settings for creating a new Landscape

Settings when creating a new Landscape.

For more information, see the Creating Landscapes page of the Unreal Engine documentation.

The first entry in the Landscape creation dialog is Material, which is the rendering material to use. You can use any Landscape rendering material, but be aware that deformations done to the Terrain are not reflected back onto the source Landscape. Instead the height changes are made available in a displacement map which can be used in a landscape rendering material to apply a world offset to each landscape vertex. AGX Dynamics for Unreal ships with an example material, M_DeformableLandscapeBase, that demonstrate the technique.

The scale in the X and Y directions set on the Landscape becomes the size of the Terrain cells in cm, which in turn define the nominal size of the soil particles spawned around shovels. A smaller scale in these directions result in a higher resolution simulation at the cost of a higher computational load. Some experimentation may be required to find a good tradeoff between resolution and simulation performance. The Z scale define the range and precision of the Landscape height offsets.

The Section Size, Sections Per Component, and Number of Components properties specify the internal layout of the Landscape. AGX Terrain is only concerned with the final number of quads, i.e., the Overall Resolution field.

14.1.2. Creating and configuring a Terrain

With the Landscape created the next step is to create and configure the Terrain. AGX Terrain is an Actor that can be found in the AGX Tab of the Place Mode. It has the following simulation related properties in its Details Panel:

Properties on a terrain.

The Source Landscape property is set to point to the Landscape that the Terrain should be associated with.

14.1.2.1. Terrain Material

A Terrain Material is similar to a Shape Material but augments it with some terrain-specific properties, such as Dilatancy Angle and Angle Of Repose Compaction Rate. See the AGX Dynamics user manual for a complete list and a description of each.

AGX Dynamics include a library of calibrated Terrain Materials and these are available in AGX Dynamics for Unreal through assets found in the AGXUnreal Content folder in the Content Browser. They are accessed either by navigating the Content Browser to AGXUnreal Content > Terrain > TerrainMaterialLibrary or by entering the search string “Terrain Material Library” in the Terrain Material property drop-down menu. The View Options option Search Asset Path must be checked in the property drop-down menu for the Terrain Material Library materials to show up.

<DESCRIPTIVE TEXT>

Finding materials in AGX Dynamic’s Terrain Material Library.

The Terrain Material Library materials should not be edited. To created modified version of these materials create a copy of the library material and edit the copy.

The Terrain tab of the AGX Dynamics Mode contains a button to refresh the Terrain Material Library, making it possible discover new Terrain Materials added to the AGX Dynamics Terrain Material Library.

14.1.2.2. Shovels

Shovels is a list of shovels that can dig in this terrain.

14.2. Creating a shovel

A Shovel is a rigid body carrying a description of how it interacts with an AGX Terrain. The description consists of three pieces of information: a top edge, a cutting edge, and a cutting direction. The following image shows what a simple shovel consisting of two boxes may look like.

A shovel built from two boxes.

A shovel built from two boxes. The arrows indicate the top edge, the cutting edge, and the cutting direction.

The Actor has the following Components:

The components that build up the example shovel.

The Components that build up the example shovel.

All edges and directions are created in a similar way.

The edge configuration options.

The configuration options available on shovel edges and directions.

Use the regular Unreal Editor move and rotate tools to position the edge and the Arrow Size to set the length of the edge. Directions are similar in that they are placed in the same way, but the Arrow Size is ignored.

Once the shovel has been configured it must be registered with the Terrain. This is done by adding it to the Terrain’s Shovels array, found in the Details Panel.

Registering the shovel with the AGX Terrain.

The Shovel is registered in the AGX Terrain’s Details Panel.

Here we may specify some additional Shovel properties that control how the shovel interacts with the terrain.

14.3. Terrain rendering

AGX Terrain gives read-only access to some of the terrain data through render targets that can be read in a Landscape render material. The first such render target is Landscape Displacement Map, which holds the height displacement of each vertex. The second render target is Terrain Particles Data Map. This render target contains two pixels per particle where the first pixel contains the location of the particle and a particle scale. The scale is relative to a SI unit cube, meaning that a scale of 1.0 should render a particle that is 1x1x1 m large, or 100x100x100 Unreal units.

If the Particle System Asset property has been set to a particle system asset, then an instance of that particle system will be spawned and the User.TargetParticleCount Niagara variable will be set to the number of currently active particles, up to the limit set by the Max Render Particles property.

Properties on a terrain.

An example terrain rendering material is provided with the plugin, stored in AGXUnreal Content/Terrain/Rendering/HeightField. It uses the height displacement map to apply a World Offset to the Landscape vertices. The material must know the size of the landscape, so create a Material Instance of the M_DeformableLandscapeBase material and set the Landscape Size parameter to the side length of the Landscape. This value is printed to the log when the Landscape is selected as the Source Landscape in the AGX Terrain.

An example particle system is provided in the AGXUnreal Content/Terrain/Rendering/ParticleSystem directory in the Content Browser.

14.3.1. Troubleshooting

14.3.1.1. Landscape not being displaced

  • Check that the Landscape has a Material Instance that supports Terrain Displacement.

  • Check that the Material Instance has the Displacement Map parameter set to a Render Target.

  • Check that the Material Instance has the Landscape Size parameter set correctly. The Landscape Size is printed to the Output Log when AGX Terrain’s Landscape property is set.

  • Check that the AGX Terrain has Enable Displacement Rendering checked.

  • Check that the AGX Terrain has Landscape Displacement Map set to the same Render Target as the Material Instance.

  • Check that the Render Target has been configured properly. - Render Target Format = R16f. - SizeX and SizeY equal to the number of Landscape vertices on each side. (Quads + 1). - Texture Address Mode = Clamp. - Mip Gen Settings = NoMipmaps. - Texture Group = Either Render Target or 2D Pixels (unfiltered).

  • Check that the Landscape is positioned at (-LandscapeSize/2, -LandscapeSize/2, 0).

14.4. Terrain in Blueprint

The AGX Terrain is an Actor class, which makes working with an AGX Terrain inside a Blueprint as easy as creating a new Blueprint class and selecting the AGX_Terrain as parent.

Creating a new Blueprint class with AGX_Terrain as parent.

Creating a new Blueprint class with AGX_Terrain as parent.

After creation, AGX Terrain properties may be accessed from the Details panel or Event Graph as usual.

Accessing AGX Terrain properties from the ``Event Graph``.

Accessing AGX Terrain properties from the Event Graph.

14.5. Troubleshooting

In some versions if Unreal Engine, particle “flickering” has been observed. The effect is purely visual and is caused by the fact that particles often changes indices between time steps as stored in the Terrain Particles Data map, which is a result of how AGX Dynamics stores particle data between time steps. This changing of indices is interpreted by Unreal Engine as a large velocity, since it may appear that one particle changes its position abruptly, thus causing some unwanted visual effects.

A workaround to this issue is to disable Motion Blur in the Particle Emitter in the Niagara System used by the AGX Terrain actor. Open the Niagara System asset used by the AGX Terrain actor in the editor and select the Render section of the Particle Emitter. From there, the Motion Blur setting can be disabled. Once disabled, compile and save the Niagara System asset.