This article details the terrain loading system available in Gaia Pro.

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, texure 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.


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 kilometres - that is 625 square kilometres. A designer can easily spend an entire work day just to design a single square kilometre - adding towns and enemy camps, distributing loot, fine tuning placements, etc.
    So you would look at 625 days alone to fill those square kilometres 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.


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.


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. 


Runtime Loading / Adding your own Loaders


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 Scene Storage
A reference to the terrain scene storage data object. This is an object that is created by Gaia initially upon terrain creation which holds data about the position and size of the different terrain scenes. You normally would not need to adjust this in any way, but you can hook up a different terrain scene storage here if you need to.
Loaders EnabledEnables / Disables Terrain Loading altogether. You should only turn that off if you would want terrain loading to stop completely, e.g. if you wanted to do some process / workflow where you would not want Gaia to interfere with its terrain loading.
Loading Time Threshold (MS)A threshold in milliseconds before Gaia will attempt to load another terrain scene in - this prevents loading spikes during runtime as it avoids multiple terrains being loaded at the exact same time. With the threshold in place, they are rather being loaded one after another, which evens out the workload across a small timespan rather than starting to load 10+ terrains in the exact same moment.
Loading Progress Timeout (MS)Threshold in milliseconds until the load progress tracking will time out. The Terrain Loader Manager offers events that a programmer can subscribe to in their own scripts to measure loading progress in their own code, e.g. to create a custom loading screen for your game. 


Scene View LoadingScene View Loading allows you to load terrains in your scene view for editing during design time. The Gaia tools can load terrains in as well, but sometimes it can be more convenient to have the scene view just load in terrains at a certain spot or around your scene view camera.
Center Loading OnWhether you want the scene view to load in terrain scenes around the World Origin, or if you want it to load around the scene view camera.
Loading RangeThe range at which Gaia should load in terrains in the scene view (either around World Origin, or around the Scene View Camera, see above)
Impostor Loading RangeThe range at which Gaia should load in Impostor terrains in the scene view (either around World Origin, or around the Scene View Camera, see above). Impostor terrains are low detail replacement meshes that act as a stand in for the full unity terrains in the distance.
If you have not set up terrain impostors yet, there will be a button that leads you to the terrain impostor creation in the terrain mesh exporter.


Terrain Caching"Terrain Caching" means a terrain will rather be deactivated than fully unloaded when it is not needed anymore. As soon as the terrain is needed again, the deactivated terrain will be activated again. Caching Terrain saves performance on frequent loading / unloading of the same terrains, but costs memory (RAM).
Cache In RuntimeWhether Gaia is allowed to cache terrains during runtime / in a standalone build.
Cache In EditorWhether Gaia is allowed to cache terrains during design time in the editor.
Total System MemoryRead-only value for the total available system memory in Megabyte.
Memory AllocatedRead-only value for the currently used system memory in Megabyte. This includes the overhead of the unity editor. The value is printed in green as long as it is below the memory threshold (see below) and red if it is above, indicating that caching will stop until memory is freed up again.
Cache Memory ThresholdDefines a maximum amount of memory the unity / standalone build process is allowed to occupy. If the allocated memory passes this threshold, Gaia will stop caching terrains and instead fully unload them to save system memory.
Keep Terrains for X SecondsDefines how long a cached terrain will be kept until it is automatically unloaded and thus removed from memory.


Collider Only Loading"Collider Only Loading" is a special mode that loads only collision information for the terrain scenes. This collision information needs to be created from the terrain mesh exporter first before this mode can be activated.
This is intended to be used in server builds only, where the server would not need to render the scene, but would still require the collision information to be loadable. This mode will only be useful for special technical reasons, but will not give you any advantages otherwise.
Collider Only Loading ActiveWhether collider loading is active or not. When activated, Gaia will only load in special collider scenes and the regular terrain will not be visible anymore.


Deactivate Runtime ComponentsWhen collider loading is active, you will additionally get options to deactivate certain runtime components of Gaia. This is again only intended for special server builds of your Gaia scene that do not render the content.
Deactivate PlayerDeactivates the Gaia player.
Deactivate LightingDeactivates the Gaia Lighting System.
Deactivate AudioDeactivates the Gaia Audio System.
Deactivate WeatherDeactivates the Gaia Weather System.
Deactivate Water
Deactivates the Gaia Water.
Deactivate ScreenshotterDeactivate the Gaia Screenshotter Tool.



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.