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.
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:
The Source Landscape property is set to point to the Landscape that the Terrain should be associated with.
22.214.171.124. 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.
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.
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.
The Actor has the following Components:
All edges and directions are created in a similar way.
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.
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.
An example terrain rendering material is provided with the plugin, stored in
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.
126.96.36.199. 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.
After creation, AGX Terrain properties may be accessed from the
Details panel or
Event Graph as usual.
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.
Niagara System asset used by the
AGX Terrain actor in the editor and select the
Render section of the
From there, the
Motion Blur setting can be disabled. Once disabled, compile and save the
Niagara System asset.