Paint holes in the terrain

To simulate cave openings and overhanging formations, such as cliffs, use the Paint Holes tool to hide a part of the terrainThe landscape in your scene. A Terrain GameObject adds a large flat plane to your scene and you can use the Terrain’s Inspector window to create a detailed landscape. More info
See in Glossary. Then use other Editor tools, such as ProBuilder, to create the cave or overhang geometry.

Access the tool

To paint a hole, in the Terrain tile’s Inspector window, select the Paint Terrain tool > tool dropdown > Paint Holes.

Tool options

The Paint Holes tool is brush-based. To learn about working with brushes, refer to Brushes.

Hide or smooth aliased edges

The Paint Holes tool is texture-based, so it can create aliased edges around holes. You can:

Hide the aliased edges with geometry, such as rock meshes.
Increase the HeightmapA greyscale Texture that stores height data for an object. Each pixel stores the height difference perpendicular to the face that pixel represents.
See in Glossary Resolution to add more texels. This increases performance requirements.

Note: When you change resolutions, the Editor copies higher resolution texture data into lower resolution texture data. In other words, it downscales. However, it doesn’t upscale.

To try a higher resolution:

Erease the parts of the hole you want to redraw with the Paint Holes tool.
In Terrain Settings, increase the Heightmap Resolution.
Draw the hole again.

For more information, refer to Terrain Settings reference.

Hole collision

A hole in the terrain is automatically excluded from the Terrain ColliderAn invisible shape that is used to handle physical collisions for an object. A collider doesn’t need to be exactly the same shape as the object’s mesh - a rough approximation is often more efficient and indistinguishable in gameplay. More info
See in Glossary, so that characters and objects can fall through it. You don’t need to manually adjust the Terrain ColliderA terrain-shaped collider component that handles collisions for collision surface with the same shape as the Terrain object it is attached to. More info
See in Glossary.

If you are creating holes in a script-based workflow, ensure that the resolution of the hole’s mask texture is equal to the resolution of the Terrain’s heightmap minus 1 (-1). For example, if the Terrain’s heightmap resolution is 1025x1025, the hole’s mask texture needs to be 1024x1024. For more information, refer to TerrainData-holesResolution.

Using a custom material

The holes functionality depends on the shaderA program that runs on the GPU. More info
See in Glossary. To allow holes in a custom Terrain material, you can either:

Use the Terrain shader the Editor provides.
Use your own shader with the following code snippet in the fragment shader:

  #ifdef _ALPHATEST_ON
      ClipHoles(IN.uvMainAndLM.xy);
  #endif

Additional resources

Sculpt the terrain with a brush

Smooth the terrain's height