Support > Documentation > Examples > Terrain Loading

Terrain Loading​

Overview

This page is divided into two sections; the first outlines the example scene for demonstration purposes and the second details programmatic loading methods and parameters. 

Check the Terrain Library for currently available terrain maps. 

Page Contents

ExampleLoadTerrain
ExampleTerrainLoading

Example Scene

Purpose

Examine available terrain maps in Split LMAB or LMAB formats, selecting between different LOD settings. 

How to Use

The terrain panel appears by default on scene launch and is divided into the following options:

GUI Debug Menu Navigation

Top Options
  • Toggle format of terrain maps; use the arrows to select between Split LMAB (default) and Single LMAB formats. System/System2 display various real-time stats.
General
  • Clear Terrain – Removes an in-progress or completely loaded terrain map from the scene.
  • Clear Data Cache – Removes …\AppData\LocalLow\USC-ICT\Ride\datacache folder; use this command in the event terrain maps fail to load properly.
  • Center Camera – Places the camera at the defined map center of the terrain map.
Load Terrain
  • Load Trees – Click to toggle off/on. Replaces low-detail tree geometry in the map with various high-fidelity SpeedTree objects; note, may not be available in all maps.
  • Use Camera Pos As Start – Terrain map streams into scene from approximate scene camera location; used in conjunction with Radius slider.
  • Radius – Adjust the slider to change the distance at which terrain tiles are rendered from the current camera position.  
  • Use Asset Bundles – Test command for future delivery method of terrain map data. 
  • Progress – Indicator of approximate completeness for the streaming of the current terrain map into the scene. 
  • Time – Tracks how long the terrain map took to stream into the scene, reaching 100% completion. 
  • Plane – Instances a simple plane object for test purposes; note, does not have tree objects.

Tip

If steaming terrain on a mobile device (Android/iOS) strongly recommend setting the Radius to a value of < 800 to avoid running out of device memory.

Load Terrain – Split LMAB Format & LOD
  • Select a terrain map, choose a LOD setting (lowest selected by default) and then click Load Terrain to begin streaming that terrain map data into the scene. Overall progress statements incrementally appear until loading finishes (1.0 value).
Load Terrain – Single LMAB Format & LOD
  • Select a terrain map, choose a LOD setting (lowest selected by default) and then click Load Terrain to begin streaming that terrain map data into the scene. Overall progress statements incrementally appear until loading finishes (1.0 value).

Important

The steaming of Single LMAB terrain maps, with the exception of those with the “s3” location designation, only function while on the ICT domain. If remote, ensure your ICT VPN is active.

Tip

Navigation Controls: 

  • WASD keys – Move the camera forward/backward/left/right
  • Q/E keys – Lower and raise the camera
  • Use the J key to toggle “free-look” mouse cursor control

Note, terrain loading menu cannot be toggled off currently. Use the top arrows to switch to the smaller system menu.

Scene Location & Name

Assets/Ride/Examples/LoadTerrain/ExampleLoadTerrain.unity

Setup Requirements 

Utilize the terrain loading capability and interface for your scene with the ExampleLoadTerrain script. 

ExampleLoadTerrain Script

Simply add this script to an empty game object in your scene: Assets/Ride/Examples/LoadTerrain/ExampleLoadTerrain.cs

Adding a Scene Persistent Terrain 

Normally terrain in the Split LMAB format streams into the scene at run-time via network or datacache folder, otherwise not appearing when working “offline” in the Unity Scene panel to create/edit a scene. Instead of using the network or datacache for run-time streaming, a terrain map can be instanced in a local scene by way of the Load Tiles script and Single LMAB terrain map format.

How to Create a Local Terrain Instance

Important

This method should only be done in special cases, as the resulting scene file can be >1GB in size, and will greatly increase the size of a standalone build, as terrain streaming is no longer used.

Additionally, the initial loading of the Single LMAB terrain format into the scene must be done while on the ICT domain. If remote, ensure your ICT VPN is active.

  1. Create New Scene.
  2. Top menu, GameObject -> Create Empty
  3. Rename object “Terrain” or similar.
  4. Inspector, Add Component -> Load Tiles (script)
  5. Set the Terrain Root parameter to the newly created game object.
  6. Set the folder path to one of the LMAB paths listed in ExampleLoadTerrain.cs. Note, only Single LMAB terrain maps will work.
  7. Lod field, input an available LOD for the terrain map, per ExampleLoadTerrain.cs listing.
  8. Ensure system connected to ICT domain (ICT VPN, if remote). 
  9. Top menu, Ride -> Terrain -> Load OWT Terrain
  10. Unity may become unresponsive for several minutes at this time, as the streaming process into the scene occurs on the main CPU thread. Duration will vary by Internet connection speed.
  11. Once complete, the terrain map appears in Scene view.
  12. The Terrain Root object will now contain all the terrain tiles beneath it. 
  13. The Terrain Lood Tiles script is no longer used inside the Terrain Root object. Uncheck its box in the Inspector panel to disable this component.
  14. Save the scene; this may take several seconds to complete.
  15. Play of the scene in the Game panel will also now take several seconds to initialize due to the increase in scene size.

Creating a Nav Mesh for AI Units

AI Units require a navigation mesh in order to utilize the terrain for simulations. Refer to Creating a Navigation Mesh from OWT Data for how to add a nav mesh to a scene. 

Programmatically Loading Terrain

The following examples describe basic and advanced methods to load terrain in a custom scene.

Basic Usage

Load a simple Plane

Passing no parameters to LoadTerrainParams() will use all defaults, and load a simple plane instead of an OWT map.

				
					
Ride.Globals.api.terrainSystem.LoadTerrain(new Ride.Terrain.Terrain.LoadTerrainParams());

Load a Terrain from a given path

Specifying a path allows you to load a given terrain. The path can be a local path, a network path, or a web url.

				
					
string path = "[Exaple terrain path]";
Ride.Globals.api.terrainSystem.LoadTerrain(new Ride.Terrain.LoadTerrainParams() { path = path, useTiles = true });

If the terrain contains LODs, you also have to specify a LOD, otherwise, it will load all the LODs contained in the terrain.

				
					
string path = "[Exaple terrain path]";
string lod = "L16";
Ride.Globals.api.terrainSystem.LoadTerrain(new Ride.Terrain.LoadTerrainParams() { path = path, lod = lod, useTiles = true });

Load a Terrain from an index into the GOList array

If your scene has a GOList GameObject populated with data, you can refer to the Terrain Paths array by specifying which index to use for loading.

				
					
int pathIndex = 0;
string lod = "L16";
Ride.Globals.api.terrainSystem.LoadTerrain(new Ride.Terrain.LoadTerrainParams() { pathIndex = pathIndex, lod = lod, useTiles = true });

Advanced Usage

LoadTerrainParams

LoadTerrainParams has many options for loading the terrain in different ways. Here are all the parameters:

				
					
public class LoadTerrainProgress
{
    public float overallProgress;
    public bool renderLoadFinished;
    public bool physicsLoadFinished;
}


public class LoadTerrainParams
{
    public string path;   // set path or pathIndex, not both
    public string pathcrc;  // this is the path to a .crc file containing the crc for the description file.  Only used if useTiles = true.  keep as null if you don't want to check the crc
    public int pathIndex = -1;
    public string lod;
    public bool loadPhysics = true;
    public bool loadTrees = true;
    public bool useTiles = false;
    public DataCache dataCache;
    public string gameObjectRootName;
    public RideVector3 startLoadingPriorityPosition;  // prioritize loading of tiles based on the distance from this position
    public int renderRadius = -1;
    public IProgress loadTerrainProgress;
}

LoadTerrainProgress parameter descriptions

This class is updated whenever progress happens during the LoadTerrain() process

  • overallProgress – An overall progress value between 0…1
  • renderLoadFinished – Set to true when the render portion of terrain loading is finished
  • physicsLoadFinished – Set to true when the physics (mesh colliders) portion of terrain loading is finished

LoadTerrainParams parameter descriptions

  • path – Path to your terrain assets.  The path can be a local path, a network path, or a web url. If you are using tiles, the path needs to point to a terrainDescription.json file.
  • pathcrc – Optional path to the .crc file of the terrainDescription.json file. Only used if useTiles is set to true. This is used to verify if the local cached copy of terrainDescription.json is up-to-date.  If not, it will retrieve the new version.
  • pathIndex – Index into the Terrain Paths array in the GOList GameObject. Specify this or path, do not specify both.
  • lod – Optional String identifier of the LOD you wish to load. If you specify a string here and the tile name contains this string, it will load the tile, otherwise all available LODs will be loaded. LODs are typically named ‘L16’, ‘L18’, etc.
  • loadPhysics – Set this to true if you wish to load physics (mesh colliders) with the terrain. Since this is very time consuming, setting this to false will speed up the loading. 
  • loadTrees – Set this to true if you wish to run through the tree replacement code.
  • useTiles – Set this to true to use the new TILE file format.
  • dataCache – Set this to a given DataCache object. This is only used when useTiles is set to false. If useTiles is set to true, it will use its own internal DataCache object.
  • gameObjectRootName – This is the root GameObject where all the terrain assets will be parented under. If the string doesn’t exist, the GameObject will be created. This needs to be unique, else it will Find() the incorrect object.
  • startLoadingPriorityPosition – This is a position in world space where the terrain tiles will start loading from. For example, if you set this to the camera’s position, it will load all the tiles in the general vicinity of the camera, giving the user immediate visual feedback that the terrain is loading.
  • renderRadius – This is a radius value specified in distance units from startLoadingPriorityPosition. Any tile outside of this radius will not be loaded. This can be done to improve loading performance if you do not need the entire terrain.
  • loadTerrainProgress – This is a user provided instance of LoadTerrainProgress that can be used to monitor the loading progress and determine when it is finished.

Advanced Usage Example

Here is an example of loading a terrain using the advanced usage.

  • This uses the new Split LMAB file format, by setting useTiles to true.
  • This loads the terrains from a web url, and specifies the .crc file to make sure the local cached copy is up-to-date.
  • loadPhysics is set to true. If we wanted faster loading performance, we could set this to false.  This can be useful if you were loading two terrain sets.  The lower LOD version would load the physics, and the second, higher LOD would skip physics loading.
  • loadTrees is set to false to improve load times.
  • gameObjectRootName is set to ‘Razish’ so that all terrain assets will be parented under this GameObject.  If it doesn’t exist in the scene, it will be created.
  • startLoadingPriorityPosition is set to the camera’s position so that it gives the user immediate visual feedback as the terrain loads.
  • renderRadius could be used to limit how much terrain is loaded.
  • loadTerrainProgress is passed in so we can provide the user feedback of the terrain loading progress and monitor when the load is finished.
				
					
var terrainPath15 = "[Exaple terrain path]";
var terrainPath15crc = terrainPath15 + ".crc";
m_terrainProgress = new Ride.Terrain.LoadTerrainProgress();
m_terrain = Ride.Globals.api.terrainSystem.LoadTerrain(new Ride.Terrain.LoadTerrainParams()
{
    path = terrainPath15,
    pathcrc = terrainPath15crc,
    loadPhysics = true,
    loadTrees = false,
    useTiles = true,
    gameObjectRootName = "Razish",
    startLoadingPriorityPosition = camera.transform.position,
    //renderRadius = 1000,
    loadTerrainProgress = new Progress((progress) =>
    {
        m_terrainProgress = progress;
    })
});

The project/effort/work depicted here was or is sponsored by the U.S. Army Research Laboratory (ARL) under contract number W911NF-14-D-0005. Statements and opinions expressed and content included do not necessarily reflect the position or the policy of the Government, and no official endorsement should be inferred.