t1k:unity:rendering:terrain

Field	Value
Module	`rendering`
Version	`3.1.7`
Effort	`medium`
Tools	—

Keywords: environment, landscape, terrain, unity

How to invoke

/t1k:unity:rendering:terrain

Unity Terrain

Terminology

TerrainData — Asset storing heightmap, splatmaps, trees, details, terrain layers
Heightmap — 2D float array [0,1] defining terrain vertex heights (indexed as [y,x])
TerrainLayer — Texture/material definition for terrain painting (replaces old SplatPrototype)
NavMeshSurface — Component for baking NavMesh on terrain geometry

Skill Purpose

Reference for Unity Terrain system (Unity 6). Covers programmatic terrain creation, heightmap manipulation, texture painting, tree/detail placement, NavMesh integration, and terrain colliders. Focused on both editor and runtime terrain generation.

Packages: Built-in UnityEngine.TerrainModule + optional com.unity.terrain-tools Related skills: unity-probuilder (modular geometry) · dots-physics (colliders) · agents-navigation (pathfinding)

When This Skill Triggers

Creating Terrain GameObjects programmatically
Using TerrainData.SetHeights(), GetHeights(), SetAlphamaps()
Configuring terrain layers, textures, materials
Placing trees and detail objects via script
Generating procedural heightmaps (Perlin noise, diamond-square)
Baking NavMesh on terrain surfaces
Terrain collider configuration

Quick Reference

Task	Reference File
TerrainData API, heightmaps, programmatic creation	terrain-api-guide.md
Terrain layers, textures, painting, splatmaps	terrain-layers-guide.md
Trees, details, NavMesh, colliders, performance	terrain-features-guide.md

Key Namespaces

using UnityEngine;              // Terrain, TerrainData, TerrainCollider, TerrainLayer
using UnityEngine.TerrainTools;  // Non-experimental terrain tools (Unity 2021+)
using UnityEngine.TerrainUtils;  // TerrainUtility, TerrainMap, TerrainTileCoord
using Unity.AI.Navigation;       // NavMeshSurface for terrain NavMesh

Key Conventions

Core workflow — programmatic terrain:

Create TerrainData asset with heightmapResolution and size
Generate heightmap float[,] array (Perlin noise, etc.)
Apply via terrainData.SetHeights(0, 0, heights) — indexed [y,x], values 0-1
Set terrainData.terrainLayers for textures
Create Terrain + TerrainCollider GameObjects
Bake NavMesh via NavMeshSurface.BuildNavMesh()

Critical rules:

Heights array indexed as [y,x] (NOT [x,y]) — common rotation bug
Height values 0.0-1.0 mapped to 0-terrainData.size.y world units
For batch edits: use SetHeightsDelayLOD() + SyncHeightmap() (faster)
heightmapResolution must be 2^n + 1 (33, 65, 129, 257, 513, 1025)
TerrainLayer replaces old SplatPrototype (deprecated since 2018.3)
Terrain collider auto-updates from TerrainData — no manual rebake
For NavMesh: add NavMeshSurface, set useGeometry = PhysicsColliders

Common gotchas:

Issue	Fix
Heightmap rotated 90 degrees	Heights indexed [y,x] not [x,y]
SetHeights slow in loop	Use `SetHeightsDelayLOD()` + `SyncHeightmap()` at end
Terrain layers not painting	Check `alphamapResolution` matches splatmap size
Trees have no colliders	Enable `TerrainCollider.enableTreeColliders`
Details (grass) not rendering	Check `detailResolution` and `detailObjectDensity`
NavMesh not baking on terrain	Add NavMeshSurface, collectObjects=All, useGeometry=PhysicsColliders

Documentation

Gotchas

Terrain heightmap resolution affects collider precision — physics raycast hits can be off by ~1 unit on coarse heightmaps.
Terrain trees are billboards past distance threshold — performance saver, but shadows disappear which players notice.
Terrain layers limit at 4 in URP without splatmap addons — going higher requires custom shader or terrain split.