2. Terrain Loading & Streaming in Gaia Pro & Gaia Pro 2021

What is Terrain Loading?

Terrains can be created / managed in 3 different ways in Gaia:

• A single terrain covering the desired target area
• Multiple terrains covering the desired target area, while the terrains are aligned in height, texture etc. at the seams so it is not apparent that the world is being assembled from multiple terrains
• Multiple terrains covering the desired target area that are stored in separate scenes. These scenes can then be loaded in and out around the player as they navigate through the terrain.

Having a single terrain in your scene is the simplest and most convenient way to handle terrains in your scene. However at certain world sizes you start to run into issues with the terrain heightmap / control texture / detail resolution, or you run into performance issues when all of your game world is being loaded in the scene at the same time. When you use multiple terrains you have the advantage that you can use higher terrain resolution values (since multiple terrains are used to cover the same area). With terrain loading from multiple terrain scenes you can additionally unload terrains distant to the player to potentially save some performance during runtime.

Most modern open-world games use one or the other form of terrain loading to manage large game worlds, often as core part of the engine itself. Gaia can help you to build such a large world by using terrain loading both during design time and runtime.

Please note: Loading scenes in Unity is significantly faster in a stand-alone build. When you run a terrain loading scene in the editor, you are more likely to encounter delays and hiccups when loading a new scene. Please judge the runtime performance only by running the project in a build, not by running it in the editor only.
 

Things to consider before creating a huge world

While Gaia makes it easier to create a large game world, please consider the following before creating a gigantic world with hundreds of terrains:

• Using terrain loading adds a lot of complexity to your game - your game code will need to be able to handle it if parts of the world (& the objects on it) are being unloaded / loaded as the player moves through the world
• Increasing the world size exponentially increases the time required for spawning textures & assets on the terrain, up to a point where it will take hours or days to generate your world
• The individual scenes still need to be loaded in and out by unity, depending on how much content there is on the individual terrain scene the scene loading process can become a performance bottleneck.
• Depending on your game type, the world will need to be filled with content as well. This can quickly take up so much time that it becomes unrealistic that you will ever finish your game. E.g. if you create a world sized 25 x 25 kilometers - that is 625 square kilometers. A designer can easily spend an entire work day just to design a single square kilometer - adding towns and enemy camps, distributing loot, fine tuning placements, etc.
• So you would look at 625 days alone to fill those square kilometers with life, without any revisions etc. which can be quite a chunk of work for smaller teams.
• Many AAA games are smaller than you think when measured in square kilometers / square miles.

This serves not to discourage you to create a large world on your own, but to be realistic about what you can achieve in relation to your team size.

How to enable Terrain Loading in Gaia Pro

Activating terrain loading in Gaia Pro is fairly simple: Just set up the amount / size of terrain tiles you want to create during world creation, and activate the following checkboxes for terrain loading:

• Create Terrain Scenes - Will create the terrains in separate unity scene files
• Unload Terrain Scenes - Will unload these terrain scenes right after creation (recommended when creating very large worlds)
• Floating Point Fix - Enables a workaround that helps with issues regarding floating point precision in the Unity Engine. For more documentation, please see here: Using the Floating Point Fix in Gaia Pro

By activating those checkboxes, your Gaia Tools and the player will automatically be set up for terrain loading. You can then continue to create your terrains as you would with a single terrain. Unity will prompt you to save the scene if you have not already - this is required from the technical side, Gaia can't create additional scenes if your "master scene" has not been saved yet.
 

Adding and removing terrains from Terrain Loading
Converting Existing Worlds from / to Terrain Loading

You might find yourself in the situation where you want to make changes to the Terrain Loading later on in development. You might want to add or remove single terrains to / from the loading, or you might want to convert a non-loading set of multiple terrains into terrain loading, or vice versa. For this, you can do the following:

Single Terrains:

To add single terrains to a terrain loading setup, you can use the "Add Terrain" tool found in the Terrain Loader Manager.



Add the single terrain from the scene to the reference slot and click "Ingest" to add the terrain into the terrain loading logic. You can remove single terrains from terrain loading with the "Remove Scene" button in the list of terrains in the Terrains panel:

Note that this will only remove the terrain from the loading mechanism. The terrain itself will not be deleted from the project, it will still sit in the terrain scenes folder of the session, so you can still access it from there to put it elsewhere if need be. If you intend to keep the terrain for later use, you should put it somewhere else as it might get overwritten e.g. if you decide to re-create the entire world from the world designer.

Converting already existing Worlds from / Adding -Removing multiple Terrains

Warning: Before attempting anything in the following section, please make sure that you back up your project first - the wrong settings being applied here can severely impact your scene!

If you have an already existing world that does NOT utilize terrain loading yet, or you have many terrains you want to add / remove you can use the Gaia Manager to change your scene setup. Navigate to the "Create Terrain" tab again, and look at the world creation settings. The settings that you enter here can be used to update your current world. This means you can convert an existing world from / to terrain loading by checking / unchecking the "Create Terrain Scenes" option. Doing so will add / remove the terrain loading from the scene. It is also possible to add / remove new rows and columns of terrains to the loading setup, these will be displayed as green boxes in the scene view. Here is an example how it would look like going from 3x3 loaded terrains to 4x4:



If you want the terrains to be added to the other borders instead, you can use the "X Offset" and "Z Offset" options in the scene view. This controls where your original terrains (purple) will be located after the update, and where the new terrains (green) will be added.


The "Recenter on Update" option will recenter your entire world so that its center sits at X=0, Z=0 again after the terrains were added / removed.
When using the "Show Terrain Toggles" option, you can choose which Terrains you want to keep when updating. This allows you to create irregular shaped setups as well:



The terrains from the above example after updating. Note how the already existing terrains were kept and new, flat terrains were added. The "unchecked" terrains were thrown out in the update:



Controlling Terrain Loading during Design Time

When creating your scene while terrain loading is active, most Gaia Tools are set up to recognize this automatically. For example the stamper (which is usually the first tool you will use) will load in terrain scenes in its range of operation automatically, same with the spawner. You should notice terrains loading in and out in the scene as you move those tools around. In the advanced options you can change the loading behavior for those tools:


 

The different load modes for those tools are:

• Disabled - will not load terrains at all
• Editor Selected - will load terrains as long as the tool is selected in the Scene Hierarchy / Inspector
• Editor Always - will keep terrains loaded even when not currently selected
• Runtime Always - will load terrains during runtime (usually used on game objects like the player rather than tools)

Additionally to the tools, there is also a general loading range in the Gaia Scene View Panel on the top of the scene view:


 

The Loading Range defines another area for loading terrains in the scene view that is independent of the individual tools. If you are unsure how large this area is, you can activate "Show Range" to show a gizmo in the scene view. You can switch the loading range to work with the "World Origin" (which is whatever your scene is being centered on, usually X=0, Y=0, Z=0) or with the "Scene View Camera". The latter will apply the loading range around the scene view camera which can be useful if you want to navigate the scene while the terrains load in around you. Please follow this link for more information about the other options in the Scene View Panel.

Last but not least you can also load individual terrains or all terrains at all from the Terrain Loader Manager. You can find the Terrain Loader Manager under "Gaia Runtime", and it has a "Terrains" panel that lists all terrains with their current load state and offers options to load / unload individual terrains or all terrains at once. Please see the section "Terrain Loader Manager" below for more information.
 

Runtime Loading / Adding your own Loaders

Please note: Loading scenes in Unity is significantly faster in a stand-alone build. When you run a terrain loading scene in the editor, you are more likely to encounter delays and hiccups when loading a new scene. Please judge the runtime performance only by running the project in a build, not by running it in the editor only.

Terrain Loading during runtime is controlled in a similar fashion as for the design time tools. To make an object load in terrains around itself, you can attach the "Gaia Terrain Loader" component to it. Gaia does this automatically for the player object in a scene where terrain loading is used, but you can set up additional Terrain Loader components on any object you like. The component has the following settings:


 

Load Mode: The load mode applied to this object. The Load Modes are the same as for the regular Gaia Tools:

• Disabled - will not load terrains at all
• Editor Selected - will load terrains as long as the tool is selected in the Scene Hierarchy / Inspector
• Editor Always - will keep terrains loaded even when not currently selected
• Runtime Always - will load terrains during runtime (usually used on game objects like the player rather than tools)

When used on a runtime object, you usually would want this to be "Runtime Always".

Refresh Rate Settings:  When the Loading Mode is set to Runtime, you can find 4 settings that control the refresh rate for terrain loading checks. In a scene with 100s of terrains it can become costly evaluate each frame whether a terrain needs to be loaded or not. You can therefore control that terrains that are closer to the loader are being checked more frequently for loading as terrains that are further away.

The "Min Refresh MS" refresh rate is used for terrains at or below the min refresh distance.

The "Max Refresh MS" refresh rate is used for terrains at or over the max refresh distance.

Anything between will be interpolated accordingly.

Loading Range Settings: The Loading Range is determined by a bounding box that determines every terrain that is touched by this box will be loaded automatically during runtime. When the checkbox for "Follow Transform" is activated, the center of this box will be the transform position of the Game Object. If not, you can enter a different point in world space for the center. You can set up the range of the box in the XYZ-dimensions as well. The box is displayed as a black Gizmo in scene view so you can review the range settings accordingly (see screenshot above).
 

Preventing the Player from falling through the Terrain

A common problem with terrain loading is that the player character / camera might fall through the terrains at scene start since the terrain takes a few milliseconds to load in the scene, which is enough for the player character falling below the terrain collider. You can prevent this with custom scripting, but there is also a small helper script included with Gaia that helps with this problem: You can attach the component "Rigidbody Wait For Terrain Load" to the game object with the Rigidbody that is affected by gravity.



This component will turn off the gravity on the Rigidbody at scene start, and only activate it after the "Activate Delay" when the terrain below the character has been loaded in. Additionally you can set up one or more components that should be activated together with the gravity. This is entirely optional and can be used e.g. to activate player controls together with the gravity on the player.


Terrain Loader Manager

When you have many tools or many different runtime loaders in the scene, it can become difficult to determine why a certain terrain is currently being loaded (or not). Under "Gaia Runtime" in the scene hierarchy you can find a "Terrain Loader Manager" Game Object that displays the Terrain Loader Manager when selected:

The Terrain Loader Manager contains additional settings for terrain loading, but also gives you an overview about all loaders that are currently in your scene and a complete list of terrain scenes and their current load state.
General Settings Panel



The following settings are accessible via the General Settings Panel:






Terrain Loaders Panel

In the "Terrain Loaders" panel you can find a list of all objects with a terrain loading component. The dropdown tells you in which mode these loaders are currently operating in.

You can use this list to analyze which objects are responsible for loading scenes and change the loading mode here directly to stop unwanted loading of terrains. You can create your own loader object by adding the Gaia Terrain Loader component to any game object. (see "Runtime Loading / Adding your own Loaders" above).

The "Select Loader" button will select the object in question and will shortly highlight the loading settings (if it is one of the Gaia tools).

Terrains Panel


 

In the Terrains Panel you can add or remove terrain scenes from loading and make sure all scenes are part of the build settings. Additionally it contains a list of all terrain scenes with an overview about the load state and which object is currently referencing (=requesting) this scene.

At the top you have the possibility to add another terrain to terrain loading:


 

You need to have the terrain in your main scene and drag and drop it from the scene hierarchy into this reference slot, then click the "Ingest" button. This will take the terrain, put it into a new terrain scene that is loadable by Gaia, and also add the required information in the terrain scene storage.

Then there is a block of general buttons that affect all terrains:

Add Scenes to Build Settings: This will add the scenes associated with the terrains to the project build settings. This is normally done when Gaia creates the scenes initially, but if the build settings / scene setup has changed it might be required to perform this again. This button will also check if your main scene is part of the build settings and whether it is on top of the loading order.

Load All: Loads in all terrain scenes at once. Warning: With a fully populated large world with 100s of terrains this can severly reduce the editor performance, or lead to crashing.

Unload All: Unloads all terrain scenes at once. If there are still loader objects active in the scene, there might be terrains loaded back in by those loaders immediately after.

Load All Impostors: Loads in all impostor scenes at once. Warning: While impostor terrains are not as heavy as the full unity terrains, they might still slow down or crash your editor if they are loaded in all at once together.

Unload All Impostors: Unloads all impostor terrain scenes at once. If there are still loader objects active in the scene, there might be impostor terrains loaded back in by those loaders immediately after.

Below the buttons you can find a list of all available terrain scenes.


 

You can choose to load / unload those scenes manually with the respective buttons. When a terrain scene is loaded in, you can see the references to this terrain scene. A "Reference" means that an object is requesting this terrain to be loaded. As long as the terrain scene has at least one reference remaining, it will stay loaded in the scene. The references created by the Gaia Panel on top of the scene view will shop up as "Terrain Loader Manager" in this view.
You can choose to either select the referencing object, or to remove the reference. When you remove a reference but the corresponding loader is still active, the reference might get recreated immediately afterwards again.
Similar information is shown for the impostor terrain for this terrain scene (if it exists).
The "Remove Scene" button will remove the terrain permanently from Terrain Loading altogether, if you want to just unload the terrain click the "Unload

You can use the information displayed in both the Terrain Loaders and Terrains Panel to analyze why a certain terrain is being loaded right now and quickly adjust the loaders in your scene to best suit your current task at hand when editing the scene.