The Vortex Earthworks feature is seamlessly integrated into Unity, allowing users to easily add, remove, and modify various Earthworks-related extensions directly within the Unity editor. Specifically, it enables users to initialize the dynamics and graphical properties of earthworks based on a Unity terrain.

The Vortex extensions are associated with specific Unity components. Typically, each extension includes multiple components that manage both the component logic and the rendering logic.

• Earthworks Zone

• Soil Particles

• Soil Dust

• Soil Materials

• Grade Quality Sensor

Open

If a Vortex scene includes any of these extensions linked to a Unity scene, the relevant component will be automatically generated within the Unity scene hierarchy. If not, the component must be manually added to the Unity scene through the Vortex menu.

Asset Bundle Compatibility

If a Unity terrain is present, the integration defaults to the streamed terrain integration, even though it is compatible with the asset bundle workflow. This means that when utilizing the integration, the user is assumed to prefer the streamed terrain approach rather than the asset bundle workflow.

Adding Earthworks Extensions

One can add the desired Earthworks extensions to the Unity scene via the Vortex → Add Vortex Earthworks Systems submenu.

Open

The selected extension will be added to the Vortex scene and the corresponding Unity game object containing the component(s) will be created in the game object hierarchy.

Vortex Earthworks Components

Vortex Earthworks Zone

The Vortex Earthworks Zone corresponds to the diggable dynamics zone and associated heightfield renderer. When an Earthworks Zone is added, or a scene containing the Vortex Earthworks Dynamics Zone and Soil Graphics extensions is synced, the following components are created:

Vortex Earthworks Zone

This component provides parameters for positioning, resizing, and adjusting the dynamic properties of the earthworks zone. Each parameter corresponds directly to a parameter in the Vortex extension. Any changes made will be reflected in the Vortex scene once the Unity scene is saved.

For a comprehensive understanding of these parameters, please visit the page at https://cm-labs.atlassian.net/wiki/spaces/VSD2410/pages/948555569/Earthwork+Zone#Configuring-the-Dynamics-Properties-of-an-Earthwork-Zone. It is important to note that only a limited selection of parameters from the Vortex extension are available in the Unity component.

For convenience, we repeat the description of the exposed parameters below:

Transform: Sets the transform of the parent earthworks zone extension in the Vortex scene. Note that in Vortex, the dynamics zone extension can be offset from its parent. This offset is reflected correctly in Unity, but cannot be modified from Unity.

Dimensions: Earthworks Zone dimensions in world units. Note the Scale parameter in the Transform of the game object is not used. The dimensions of the earthwork zone are illustrated with the orange gizmo that appears when the game object containing the Earthworks Zone Component is selected, and may be toggled by the global gizmo visibility toggle.

Shear Strength (%): Scales the shear strength of the soil in an Earthwork Zone, affecting its resistance to shear forces. Reducing this value will make the soil slip more easily, hence reducing the angle of repose. Moreoever, less force will be needed to cut through the soil.

Flow Velocity Scale (%): A parameter controlling the flow velocity of the soil.

Diggable: Toggles diggability of earthworks zone. True by default.

Initial Relative Density: Soil initial relative density (%).

Contact Material: Earthworks Zone contact material. If specified contact material doesn't exist in the material table, the default material is used. Note that the default Earthworks Zone contact material is usually different from the default contact material in the Material Table. If you specifically want to use the default contact material of the Material Table, you need to explicitly set this value to “Default”.

Cell Size: Earthworks Zone cell size in world units. Note that if this parameter is too small, the performance of the simulation can be severely impacted.

Replacement Mesh Layer: Defines the terrain layer to use on the replacement mesh. The dominant terrain layer is used if not specified.

Vortex Height Field Script and Renderer

These components correspond to the Vortex soil graphics extensions. The Vortex dynamics zone is a deformable mesh whose corresponding graphical mesh is updated each frame. If asset bundle prefabs are not used, then the Terrain Capture Resolution has no affect.

The undeformed soil texture is taken to be the texture of the dominant material layer in the Unity terrain over the earthworks zone. This texture can be changed manually if desired.

On the other hand, the deformed soil texture must be manually specified by the user. Please refer to the page below on customizing the graphical features of the Earthworks zone and related extensions:

Customizing Earthworks and Soil Graphics in Unity

Vortex Earthworks Zone Runtime Behaviour

If an asset bundle prefab is not used, there is no edit time representation of the Earthworks Zone heightfield collider or graphical mesh.

• The Earthworks Zone is only created for Vortex when Play mode is started. The integration makes a box around the zone, and replaces the terrain inside the box with a mesh that contains the diggable area. Due to the diggable area, in general, requiring a finer mesh than the terrain, sometimes the replacement mesh will not exactly match the original

• the tiles intersecting the dynamics zone are streamed to Vortex and used to create the heightfield collider used by the Dynamics Zone extension to define the diggable mesh; thus there is no edit time representation of the heightfield colliders, and no way to serialize the heightfields in the Vortex scene

To summarize, this implies the following limitations on the workflow:

Vortex Soil Components

Detailed information about the Vortex extensions corresponding to these components can be found here. We repeat the description of the exposed parameters here for convenience.

Vortex Soil Particles

This extensions is required for both the mass-conserving dynamics of soil transfer and visualizing the soil particles corresponding to dug soil.

Vortex Soil Particles Meshes Renderer

Mesh Visibility Percentage: Fraction of particles generated that are actually displayed.

Meshes and Materials: List of the meshes and corresponding materials for particle graphical assets.

Vortex Soil Particles SSM Renderer

Material Coverage: When applying the SSM Material to the Screen Space Soil Mesh (SSM), this value (in world units) represents the amount of coverage before repeating the material.

SSM Depth Offset: Shifts the SSM particles towards the camera (positive value) or away from the camera (negative value). The value controls how much of the triangle meshes will be visible through the SSM soil. The valid range is -0.5 to 0.5 world units.

Filter Blur Sample Count: Specifies the number of samples the blurring kernel will use. The kernel will sample Filter Blur Sample Count * Filter Blur Sample Count pixels, and if no noise is applied (see below for Noise Influence) the kernel will be square. Without any noise applied, Filter Blur Sample Count needs to be a large value to remove the repeating artifacts. The valid range of values is 2 to 30.

Filter Size and Filter Pixel Limit: Specify the sizes of the blurring kernel. Filter Size sets the size of the blurring kernel in meters (valid range is 0.0 to 0.6 in world units), and the Filter Pixel Limit sets the maximum size of the kernel in pixels (valid range is 0 to 200). During the SSM shader execution, the kernel size in meters will be pegged to the size in pixels. The pixel limit is relevant only when zooming in. The recommended workflow is to initially set the pixel limit to a large value (e.g., 200) then tweak the Filter Size value. After an acceptable Filter Size value is found, then adjust Filter Pixel Limit.

Noise Texture: The noise functions are baked into a texture. If no noise texture is supplied, a default Perlin noise texture will be assigned. Otherwise, you can supply a custom noise texture by dragging a Unity Texture 2D asset into the field.

Noise Frequency: Controls the amount of detail as a result of the noise offset. The valid range of values is 0.0 to 30.0.

Noise Influence: Controls the amplitude of the noise offset. Increasing the influence increases the potential sampling area of the depth blurring kernel. The valid range of values is 0.0 to 300.0.

Normal Blur Samples Count and Normal Blur Radius: Analogous to the Filter Blur parameters, but applied to the normal map.

SSM Material: The material used to render the SSM particles. Can be any Unity Material. By default, no material is set.

Soil Materials

This extension is essential for the proper functioning of both the Soil Particles and the Grade Quality Sensor. However, it currently does not provide any parameters that can be adjusted within Unity. To modify the soil material parameters, you will need to access the Vortex Scene that includes the Soil Materials extension in the Vortex editor and implement your changes there. Please refer to the section on soil tuning workflow below for guidance.

Soil Dust

A purely visual effect. This extension does not affect the dynamics of the earthworks zone or particles and is entirely optional.

Effect Asset: This component requires a Unity Effect. A defaultSoilDustEffect is provided by the integration if none is specified.

Particle Texture: Texture for dust particles. A default DustTexture is provided by the integration if none is specified.

Emission Rate (Hz): Determines how many particles are emitted when an impact event is received.

Particle Lifetime (s): Determines how long the dust particle will exist after its creation.

Spray Cone Angle (degrees): Angle that specifies direction perturbation applied to particle velocity.

Spray Linear Speed Range: Determines the range of linear speeds the particles can travel.

Gravity Acceleration: Offset to the gravitational acceleration applied to the particle.

Drag Coefficient: Velocity damping applied to particles.

Color Over Life: Sets a variance in color for the particles over their lifetime.

Size Range: Determines the range of the particle size.

Vortex Grade Quality Sensor

Another purely visual tool that indicates if the soil depth is appropriate for e.g. a training scenario or engineering simulation.

Mesh: The mesh that will be instantiated at each point.

Sub Mesh Index: The sub mesh index to use.

Mesh Offset: Base offset position in meters.

Mesh Orientation: Base offset orientation in degrees.

Mesh Scale: Base mesh scale.

Material: The material used to render the point cloud.

Soil Tuning Workflow

At the beginning of the simulation, the Earthworks Zone does not provide an editable representation of the terrain heightfields. Additionally, the Soil Materials parameters remain hidden within Unity. As a result, adjusting the soil materials in the unified Earthworks integration requires a multi-step iterative approach.

First, ensure you are set up for debugging in Unity (Debugging the simulation content ). With the dynamics visualizer and content debugger active:

1. Experiment in Unity

While simulating in Unity, you can move within and dig in the earthworks zone. While only a handful of parameters are exposed in Unity components, the content debugger lists the inputs, outputs and parameters of every extension.

2. Update the Vortex scene.

Having identified the changes you want to make, stop the Unity simulation and open the Vortex scene. For example, the Vortex scene used in our Terrain Demo has the following extensions:

The Soil Materials extension, for instance, has the following parameters:

These parameters can be changed, and saved.

3. Test changes

After saving your changes, reconnect the Vortex scene to the Unity project. Your modifications will automatically synchronize with the Unity components, eliminating the need for any additional adjustments. Switch back to simulation mode and verify that your changes produce the intended results.

Performance Tuning

There is no significant overhead when using the Earthworks integration in Unity compared to the performance of running earthwork in Vortex only. In particular, performance can degrade if:

• the earthworks zone is too large

• the grid resolution is too fine

• the soil particle count is too large