This documentation is for a prerelease version of O3DE. Click here to switch to the latest release, or select a version from the dropdown.


Terrain Gem

The Terrain Gem implements a terrain system, which is a system that defines the geometry, color, and surface types for a ground surface, renders the surface, and provides a physics representation.


The Terrain Gem has the following key features:

  • Maps height, color, and surface data to regions of the world.
  • Provides gradient-based and shape-based authoring tools and workflows to create and manipulate the terrain data.
  • Exposes a queryable API that is usable by both simulation and rendering.
  • Renders an efficient, high-quality terrain visualization across the view distance.
  • Integrates with physics to provide a “physical” simulation of the terrain in the virtual world.

Enabling the Terrain Gem

To enable the Terrain Gem, do the following:

  1. Use Project Manager or the command line to add the Terrain Gem to your project.
  2. Build your project using Project Manager, Visual Studio, or CMake.

Getting started

Refer to the Create terrain from images tutorial for step-by-step instructions on authoring terrain.
Refer to the Terrain Developer Guide for information on using and extending the terrain system as a developer.

Level Components

Terrain WorldEnables the terrain system and provides the data required for other terrain components.
Terrain World DebuggerOffers a number of terrain debugging features. These visualizations are entirely optional, and can be toggled on or off individually.
Terrain World RendererVisualizes terrain in the world and controls the global terrain rendering properties.


Terrain Layer SpawnerSpawns a terrain region contained within configurable bounds, and allows prioritization of overlapping terrain layers.
Terrain Height Gradient ListProvides terrain height data from a list of gradients.
Terrain Surface Gradient ListDefines mappings between a gradient and a surface type on a terrain layer.
Terrain Macro MaterialProvides a macro level method of defining the appearance of a region of terrain.
Terrain Surface Materials ListDefines mappings between a surface type and a render material.
Terrain Physics Heightfield ColliderProvides terrain data to a physics collider in the form of a heightfield and surface to material mapping.


The Terrain Gem uses the following Console variables (CVARs) either at runtime via the console, or by placing them in configuration. See the general CVAR guide for more information on configuring CVARs.

Terrain Physics

cl_terrainPhysicsColliderMaxJobsThe maximum number of jobs to use when updating a Terrain Physics Collider (-1 will use all available cores).
physx_heightfieldDebugDrawDistanceDistance for PhysX Heightfield debug visualization in meters.
physx_heightfieldDebugDrawBoundingBoxDraw the bounding box used for heightfield debug visualization.
physx_heightfieldColliderUpdateRegionSizeSize of a heightfield collider update region in meters, used for partitioning updates for faster cancellation.

Terrain Rendering

r_terrainClipmapDebugEnableTurn on clipmap debug rendering on the screen.
r_terrainClipmapDebugOverlayThe clipmap type to render on the screen. 0 is none, 1 is the macro texture clipmap, 2 is the detail texture clipmap.
r_terrainClipmapDebugClipmapIdThe clipmap channel to be rendered on the screen. 0 is macro color, 1 is macro normal, 2 is detail color, 3 is detail normal, 4 is detail height, 5 is detail roughness, 6 is detail specular, 7 is detail metalness, and 8 is detail occlusion.
r_terrainClipmapDebugClipmapLevelThe clipmap level to be rendered on the screen.
r_terrainClipmapDebugScaleThe size multiplier of the clipmap texture’s debug display.
r_terrainClipmapDebugBrightnessA multiplier to the final output of the clipmap texture’s debug display.
r_terrainDebugDetailMaterialsEnable detail material id visualization.
r_terrainDebugDetailImageUpdatesEnable visualization of detail material update regions.
r_debugTerrainLodLevelsEnable debug coloring for terrain mesh LODs.
r_debugTerrainAabbsEnable visualization of terrain sector AABBs.