Unity World Building

Unity World Building

Retrieval Sources

ProBuilder coverage note: local docs have only the package landing-page stub (description: "Build, edit, and texture custom geometry in Unity... in-scene level design, prototyping, collision meshes"; keywords: 3d, model, mesh, modeling, geometry, shape, cube, blender, max; no tutorials, no ScriptReference). Answer ProBuilder questions from general Unity 6 pretrained knowledge, explicitly say retrieval coverage is thin, and point to docs.unity3d.com/Packages/com.unity.probuilder@latest for authoritative API/tutorial details.

Key Guidelines

Terrain Heightmap Sculpting

A Terrain's height is not per-vertex mesh geometry — it is a grayscale heightmap texture where each texel stores a height value from 0 to 1, scaled by the tile's TerrainData.size.y. Two hard constraints from terrain-Intro-to-Height.html shape every sculpting decision: each tile has a maximum height (Terrain Settings > Mesh Resolution > Terrain Height) beyond which the top of a mountain simply flattens with no further detail possible, and you cannot sculpt below the tile's GameObject y-position — for sunken features (lakes, riverbeds, canyons) you must first use Set Height to lower a starting plateau, then sculpt within it. Heightmap resolution (TerrainData.heightmapResolution) is clamped by Unity to one of 33, 65, 129, 257, 513, 1025, 2049, or 4097 texels; picking this value is a one-time-cheap, change-later-expensive decision (per terrain-Heightmaps.html) because resampling an existing heightmap to a new resolution can distort or lose sculpted detail, so lock in a target resolution before investing sculpting time. Above raw Raise/Lower/Set Height/Smooth, Unity 6 ships Stamp (brush-shaped height stamping), Bridge (connects two picked points with a ramp), Clone (samples height from one area and paints it elsewhere), Terrace, and a full noise-brush suite (Perlin/ridge/Voronoi et al. via terrain-Sculpt-Noise-Tool.html) plus Transform brushes (Pinch/Smudge/Twist) for reshaping already-sculpted terrain, and a three-pass erosion simulation (Hydraulic — sediment travels with water and can move long distances, carving riverbanks; Thermal — sediment settles at its angle of repose, limiting how steep cliffs/mountains can form and not traveling far; Wind — sediment travels far and builds dune-like features at the end of its path) for physically-plausible large-scale landforms.

Runtime/editor scripting against the heightmap has a critical performance fork: TerrainData.SetHeights recomputes all LOD and vegetation placement information on every call, which is expensive enough to stutter interactive editing or per-frame runtime modification. TerrainData.SetHeightsDelayLOD writes the same height data without that recompute (the terrain may transiently render at the wrong LOD), and you call TerrainData.SyncHeightmap() once after a batch of edits (e.g., on mouse-up, or once per streaming-tile load) to flush the deferred LOD/vegetation update.

using UnityEngine;

public class CraterStamper : MonoBehaviour
{
    public Terrain terrain;
    public Vector2Int centerTexel = new Vector2Int(256, 256);
    public int radius = 40;
    public float depth = 0.05f; // normalized height units (0..1)

    public void StampCrater()
    {
        TerrainData data = terrain.terrainData;
        int size = radius * 2;
        int xBase = Mathf.Clamp(centerTexel.x - radius, 0, data.heightmapResolution - size);
        int yBase = Mathf.Clamp(centerTexel.y - radius, 0, data.heightmapResolution - size);

        // heights array is indexed [y, x], values 0..1
        float[,] heights = data.GetHeights(xBase, yBase, size, size);
        for (int y = 0; y < size; y++)
        {
            for (int x = 0; x < size; x++)
            {
                float dist = Vector2.Distance(new Vector2(x, y), new Vector2(radius, radius));
                float falloff = Mathf.Clamp01(1f - dist / radius);
                heights[y, x] = Mathf.Max(0f, heights[y, x] - depth * falloff * falloff);
            }
        }

        // Interactive/per-frame path: cheap write, no LOD recompute yet.
        data.SetHeightsDelayLOD(xBase, yBase, heights);
    }

    void OnMouseUp() => terrain.terrainData.SyncHeightmap(); // flush LOD/vegetation once, on release
}

Terrain Texture Painting & Layers

Texture painting is driven by Terrain Layers (TerrainLayer assets: a diffuse texture, optional normal map, optional mask map bundling smoothness/metallic/AO channels, plus tile size/offset), blended per-pixel via an alphamap (splatmap) baked into TerrainData. Per terrain-PaintTexture.html, the very first Terrain Layer you add flood-fills the entire tile — there is no "default/no layer" state, so plan your base layer (the tiling ground texture that shows through everywhere nothing else is painted) before adding detail layers. Terrain Layers are standalone Assets, reusable across every tile in a scene, so a shared layer library (rock, grass, sand, snow, dirt-path) keeps texel-level identity consistent across a multi-tile world and lets you re-tune one texture globally. Each additional layer costs one more alphamap sample per rendered terrain pixel, so layer count is a direct fill-rate cost, not just an authoring convenience — consolidate similar surfaces (e.g., one "rock" layer with height/slope-based procedural variation via a custom shader) rather than adding a new layer for every visual variant.

Alphamap scripting reads/writes a float[,,] array indexed [y, x, layerIndex] where the last axis sums to 1 per texel across all layers on that tile:

using UnityEngine;

public class SlopePainter : MonoBehaviour
{
    public Terrain terrain; // Layer 0 = grass, Layer 1 = rock

    void Start()
    {
        TerrainData data = terrain.terrainData;
        float[,,] map = new float[data.alphamapWidth, data.alphamapHeight, data.alphamapLayers];

        for (int y = 0; y < data.alphamapHeight; y++)
        {
            for (int x = 0; x < data.alphamapWidth; x++)
            {
                float normX = x / (float)(data.alphamapWidth - 1);
                float normY = y / (float)(data.alphamapHeight - 1);
                float angle = data.GetSteepness(normX, normY); // 0..90 degrees
                float rockWeight = Mathf.Clamp01(angle / 45f);  // steep => more rock

                // array is [y, x, layer]
                map[y, x, 0] = 1f - rockWeight; // grass
                map[y, x, 1] = rockWeight;      // rock
            }
        }
        data.SetAlphamaps(0, 0, map);
    }
}

Tree & Detail Placement

Trees and details (grass/foliage) paint onto the terrain through prototypes: TreePrototype entries reference a prefab, DetailPrototype entries reference either a mesh or a texture. Trees render as real instanced GameObjects at close range and crossfade to camera-facing billboards at distance (treeBillboardDistance/treeCrossFadeLength on Terrain, or the global QualitySettings.terrainBillboardStart); per terrain-Tree-Performance.html, tree performance is dominated by polygon count of the tree model itself, so simplify meshes/reduce leaf-and-branch counts before relying on distance culling to hide the cost, and always verify the visible LOD/billboard transition distance doesn't create a "pop" the player notices. Detail rendering (terrain-Grass.html) offers four render modes with real cost differences: Instanced Mesh (GPU-instanced, Unity's recommended default for most cases), Vertex Lit mesh (all instances combined into one static mesh — no GPU instancing, so instance-count scaling is worse, and shading is simplified), Grass mesh (like Vertex Lit but normals are forced upward and the mesh reacts to wind), and Grass Texture (billboard quads generated directly from a texture with optional camera-facing). Detail density maps (TerrainData.SetDetailLayer) are per-pixel grayscale layers where each texel's value is the number of detail instances to scatter in that cell, and TerrainData.detailScatterMode controls whether that count is interpreted deterministically or randomized — detailResolutionPerPatch governs the culling-patch granularity, trading CPU culling overhead against per-patch draw-call batching.

using UnityEngine;

public class DetailThinner : MonoBehaviour
{
    public Terrain terrain;
    public int detailLayer = 0;
    public float threshold = 3f;

    void ThinSparseGrass()
    {
        TerrainData data = terrain.terrainData;
        int[,] map = data.GetDetailLayer(0, 0, data.detailWidth, data.detailHeight, detailLayer);

        for (int y = 0; y < data.detailHeight; y++)
            for (int x = 0; x < data.detailWidth; x++)
                if (map[x, y] < threshold) map[x, y] = 0; // cull sparse/isolated grass instances

        data.SetDetailLayer(0, 0, detailLayer, map);
    }
}

Terrain Performance (Pixel Error, LOD, Draw Distance)

Terrain LOD and draw-distance behavior is controlled by a mix of global QualitySettings terrain knobs and per-Terrain instance overrides gated by Terrain.ignoreQualitySettings/TerrainData's TerrainQualityOverrides flags — this lets most tiles follow the project's quality tier while a hero/close-up tile pins tighter settings. terrainPixelError (mirrored per-instance as Terrain.heightmapPixelError) is the single highest-leverage LOD knob: it caps the allowed screen-space error (in pixels) between the simplified LOD mesh and the true heightmap, so raising it aggressively reduces triangle count and GPU cost at the price of visible geometric popping/simplification, especially on ridgelines. terrainBasemapDistance (Terrain.basemapDistance) controls the distance at which Unity swaps from sampling individual Terrain Layers to a single pre-composited basemap texture — pushing this closer to camera trades per-layer texture fidelity at range for fewer texture samples. terrainTreeDistance, terrainBillboardStart, terrainFadeLength, and terrainDetailDistance/terrainDetailDensityScale govern tree culling, billboard crossfade start/length, and detail (grass) draw distance/density respectively; terrainMaxTrees caps full-mesh (non-billboard) tree instances rendered at once, which matters most on lower-end hardware with dense forests. Tune these per platform quality tier rather than globally maxing them out — the defaults are frequently too generous for mobile and tank frame time via both fill rate (alphamap layers, detail overdraw) and vertex/LOD-recompute cost.

Multi-Tile / Large Terrains

A single TerrainData becomes unwieldy well before "open world" scale — high heightmap/alphamap resolution on one giant tile makes every paint-tool stroke and every SetHeights LOD recompute proportionally more expensive, and streaming/culling only works at whole-tile granularity. The documented pattern (terrain-CreateNeighborTerrains.html) is multiple Terrain GameObjects, each with its own TerrainData, positioned edge-to-edge and explicitly wired as neighbors (Terrain.SetNeighbors(left, top, right, bottom), or auto-connect via matching Terrain.groupingID + allowAutoConnect) so Unity stitches height/normal data across the seam and avoids visible cracks or lighting discontinuities at tile borders. TerrainUtils.TerrainMap and TerrainUtils.TerrainUtility.AutoConnect provide a scripting-side API for building/repairing the neighbor graph across a whole grid of tiles at once rather than wiring each pair by hand. Keep per-tile resolution modest and uniform (mismatched heightmap resolutions between neighbors can produce seam artifacts) and treat "how many meters per tile" as a scene-authoring decision made once, early, since re-tiling an already-sculpted large world means re-slicing height/alpha/tree data across new boundaries.

using UnityEngine;

public class NeighborWiring : MonoBehaviour
{
    // Assumes terrains are laid out in a grid and named/ordered consistently.
    public void WireGrid(Terrain[,] grid)
    {
        int w = grid.GetLength(0), h = grid.GetLength(1);
        for (int x = 0; x < w; x++)
        {
            for (int z = 0; z < h; z++)
            {
                Terrain left  = x > 0 ? grid[x - 1, z] : null;
                Terrain right = x < w - 1 ? grid[x + 1, z] : null;
                Terrain bottom = z > 0 ? grid[x, z - 1] : null;
                Terrain top    = z < h - 1 ? grid[x, z + 1] : null;
                grid[x, z].SetNeighbors(left, top, right, bottom);
            }
        }
    }
}

ProBuilder Whiteboxing (pretrained knowledge — local docs are thin)

Local documentation for ProBuilder is limited to the package landing-page stub — treat everything below as general Unity 6 pretrained knowledge, not a grounded citation, and say so when answering. ProBuilder is an in-Editor mesh modeling tool for building, editing, and texturing custom geometry directly in a scene — its primary use is level-design whiteboxing/greyboxing: fast, parametric blockout geometry (rooms, corridors, staircases, simple props) that supports on-the-fly playtesting without round-tripping to an external DCC tool. Parametric shapes (cube, stair, arch, cylinder, plane, etc.) start editable at the vertex/edge/face level with live UV editing, vertex-color painting, and per-face material/texture assignment; ProBuilder can also generate a matching collision mesh directly from the level geometry, which is convenient for iterating collision alongside visuals. Because ProBuilder meshes retain editor-side parametric/editable data, the standard production workflow is: whitebox and iterate freely with ProBuilder during layout/pacing passes, then either replace the blockout with authored art meshes, or explicitly export/convert the ProBuilder object to a standard static Mesh asset before shipping — the model-export feature exists specifically to let you refine a ProBuilder blockout in an external 3D tool if it's being kept as final geometry. Skipping this conversion step ships editor-only mesh authoring data and extra runtime overhead in the build.

Combining Terrain with Static Meshes

Heightmap-based Terrain is fundamentally a 2.5D height field: one height value per (x, z) grid cell, so it geometrically cannot represent overhangs, caves (without the separate Holes system), vertical cliffs with undercuts, or interior spaces. Anything requiring hard edges, movement, or true 3D topology — buildings, bridges (as physical geometry, not the Bridge sculpt tool), rocks with overhangs, tunnels, interiors — belongs in authored static/skinned meshes (or ProBuilder blockouts) placed on top of or embedded into the Terrain, not sculpted into it. Terrain.SampleHeight/TerrainData.GetInterpolatedHeight are the standard bridge for procedurally aligning placed meshes to the terrain surface (e.g., snapping a building's foundation or a prop's Y position to the ground at spawn time), and TerrainData.SetHoles/GetHoles (a separate boolean mask texture, resolution set independently via holesResolution) is the supported way to cut a cave mouth or tunnel entrance into the heightmap surface so a hand-built interior mesh can occupy that space without z-fighting or the terrain mesh poking through.

using UnityEngine;

public class SnapToTerrain : MonoBehaviour
{
    public Terrain terrain;

    void OnValidate()
    {
        if (terrain == null) return;
        Vector3 pos = transform.position;
        pos.y = terrain.SampleHeight(transform.position) + terrain.GetPosition().y;
        transform.position = pos;
    }
}

Common Mistakes

Quick Reference

Advanced Notes

Open-world streaming terrain tiles. For worlds too large to keep every tile resident, the neighbor-terrain tiling pattern doubles as a streaming unit: each Terrain/TerrainData pair is a natural load/unload granule, since Unity already treats tile boundaries as authoritative for LOD, culling, and neighbor stitching. A practical approach is to keep TerrainData assets un-loaded (e.g., addressable or Resources/AssetBundle-backed) until the player crosses a distance threshold from a tile's bounds, instantiate/enable the Terrain GameObject and assign terrainData on demand, then call Terrain.SetNeighbors against whichever adjacent tiles are currently resident (passing null for not-yet-loaded neighbors, then re-wiring once they stream in) to avoid seam artifacts at the streaming frontier. Because tree/detail data lives inside TerrainData alongside the heightmap, streaming a tile in/out inherently streams its foliage too — budget for the SetTreeInstances/detail-layer population cost on load, which is comparable to (and additive with) the heightmap LOD recompute cost discussed above; prefer populating instances via a background job or spreading the population work across several frames rather than a single synchronous call on tile activation, since Terrain.Flush()/the initial LOD build after data assignment is not free. Keep world-unit tile size and heightmap/alphamap resolution uniform across the streaming set, both to avoid seams (per Common Mistakes) and because non-uniform tiles complicate the distance-based load/unload threshold math. For very large worlds, consider whether the far-distance tiles need full-resolution TerrainData at all — a common pattern is a lower-resolution "impostor" heightmap for distant tiles (or relying on terrainBasemapDistance/aggressive terrainPixelError for those tiles specifically via per-tile TerrainQualityOverrides) so streaming budget goes toward tiles near the camera.

Runtime terrain modification performance. Every runtime deformation path (explosion craters, procedural digging, vehicle-tire ruts, building foundations) funnels through the same cost centers documented above, and they compound under repeated/continuous modification: (1) heightmap writes — always prefer SetHeightsDelayLOD inside the modification loop and batch a single SyncHeightmap() call after each discrete interaction (e.g., once per explosion, once per drag-release, not once per physics tick) rather than syncing per-write; (2) collider sync — TerrainCollider regenerates its physical collision mesh in response to heightmap changes, which is a real cost on large or frequently-edited areas, so throttle how often modified regions get resynced against physics (e.g., accumulate several deformation events, then sync once) rather than triggering a physics rebuild every frame; (3) alphamap writes for blended damage decals (scorch marks, tire tracks) are comparatively cheap per-call but still scale with the affected rect size — clamp modification rects tightly to the actual brush radius rather than always touching a fixed oversized region; (4) tree/detail instance changes triggered by terrain damage (knocking down foliage) go through the same full-array SetTreeInstances/SetDetailLayer writes as authoring-time painting, so for frequent small changes prefer reading, mutating only the affected sub-range, and writing back rather than reconstructing the whole instance array; (5) use TerrainData.DirtyHeightmapRegion/DirtyTextureRegion plus the TerrainCallbacks events to drive downstream systems (minimap generation, nav-mesh rebaking, save-data diffing) off the actual dirtied rect instead of the whole tile, since a full-tile reaction to every small edit is the most common way runtime terrain deformation systems silently become the frame-time bottleneck. Where deformation needs to happen many times per second (e.g., real-time vehicle deformation), consider decoupling the visual heightmap update (per-frame, SetHeightsDelayLOD, no collider sync) from a physics collider resync that only runs every N frames or on a distance/velocity-gated trigger, accepting brief visual/physical mismatch in exchange for not rebuilding collision geometry every tick.