Terrain

What Terrain mode does#

Terrain is the first of the three edit modes (top-right Edit: toggle, default key F1). It owns the ground itself: the Terrain3D height surface, the textures painted onto it, holes, the active region cells, and the height-layer brushes described in Height layers. While you are in Terrain mode the viewport hides every placed prop, object and marker so nothing gets between you and the ground; switch to Objects or Region when you want them back.

The mode has three working surfaces:

• The tool column down the right edge of the viewport, between the 3D view and the right panel. Hover any tool for its name and current shortcut.
• The brush settings bar along the bottom, which changes with the tool.
• The right panel's Textures tab, with the Library panel docked beneath it.

Map-wide settings (sky, lighting, fog, water, terrain mesh quality) live in the left panel's Nodes tree and Inspector.

Sculpting#

Tools#

Tool keys are plain letters with no modifier and are rebindable under Settings > Keybinds in the Terrain Tools group.

Brush settings#

The bar below the viewport shows the settings the armed tool uses. These are the shared Terrain3D brush settings; the height-layer tools use the same ones.

Click a setting's label to reset it to its default. The bar also has an advanced submenu with Add regions while sculpting (on), Align to view (on), Show cursor while painting (on), Gamma (1.0), Jitter (50 %) and Crosshair threshold (16 m).

Procedure: shape a hill and flatten a plateau#

1. Switch to Terrain mode and press R for Raise.
2. Set Size to the width of the hill and Strength to taste, then click-drag over the ground. Hold Ctrl to lower instead.
3. Hold Shift and stroke again to smooth the result.
4. Press H for Height, Ctrl+click the spot whose height you want to keep, then paint the area you want level. The center of the brush snaps to the value; the edges blend.
5. Press Ctrl+Z if a stroke went wrong. Each sculpt operation is one undo step, and the last 20 terrain snapshots are kept.

Texture painting#

The Textures tab#

In Terrain mode the right panel shows the map's texture slots. Each tile carries a numbered badge (slot 1 upward); up to 32 slots fit on a map. A slot with a texture can be selected by clicking it or by pressing its number key 1 to 9 while a texture brush is armed, and the texture currently being painted is previewed in a small overlay at the bottom-right of the viewport.

The Texture window shows the Albedo Texture and Normal Texture side by side and the material values beneath them: Name, Albedo Color, Normal Depth, AO Strength, Roughness, UV Scale, Vertical Projection, Detiling Rotation and Detiling Shift. OK applies, Cancel discards.

The texture Library#

The Library panel under the Textures tab is the project's texture library (stored at assets/textures/, shared by every map in the project). It has a search box, folder breadcrumbs ending in New Folder and Clean Unused, a thumbnail grid, and a footer with + Add Texture and a thumbnail size slider.

To add a texture, press + Add Texture or drop image files straight onto the grid. The Add Texture dialog has a Name field and two drop slots, Albedo and Normal (optional); drop a whole PBR set (color, normal, roughness, height) and it is packed automatically. Right-click a library tile for Add to Map, Edit Defaults..., Rename, Move to Root and Delete from Library; right-click a folder for Open, New Subfolder, Rename Folder and Delete Folder. Clean Unused deletes texture files under assets/textures/files/ that no map or the library still references.

Paint and spray#

Both show the brush shape and Size plus a Texture on/off checkbox, a Slope range (0 to 90 degrees) that limits painting to ground within that steepness, and Angle and Scale controls (with pickers, and Dynamic angle) for rotating and resizing the texture tiling as you paint.

Autoshader#

Paint Autoshader (U) marks areas where the terrain textures itself automatically by slope and height, using two slots: a base for flat ground and an overlay for steep ground. The Disable Autoshader half of the button (or Ctrl) hands an area back to manual painting. The slots and the map-wide switch are in the Terrain3D inspector under Autoshader: Enabled, Base Texture (slot index, default 0) and Overlay Texture (default 1). A map created with an Autoshader texture on the create screen starts with this switched on.

Holes#

Add Holes (O) cuts the terrain mesh away under the brush so you can see through it; the Remove Holes half of the button (or Ctrl) fills it back in. A hole removes every face touching the carved vertices, so the visible opening is slightly larger than the brush. The brush decal turns black while the tool is armed.

Terrain regions#

Terrain only exists inside active region cells, each 64 x 64 tiles (32 world units); see the overview for how they relate to tile coordinates. The Add Region tool (G) shows the instruction "Click the terrain to add a region. CTRL+Click to remove." in place of brush settings: click an empty cell to activate it, Ctrl+click an active cell to delete it and everything painted in it. With Add regions while sculpting on (the default), sculpting off the edge of the terrain activates cells as you go.

The Terrain3D inspector's Info section shows how many regions the map has. Turn on View Region Grid and View Region Labels in the View menu to see cell edges and coordinates.

Map environment#

Select a node in the left panel's Nodes tree to edit it in the Inspector below. The + button next to the tree adds a DirectionalLight3D if the map has none.

Terrain3D#

Water#

Choosing Water as the background type turns on the map's water plane. It sits at the waterline (just below 0 on the Y axis by default, where Island maps put the sea) and is saved to the map's water.json together with its colours and surface values: enabled, level, water_color, deep_color, highlight_color, fresnel_power, highlight_strength, roughness and metallic. The water level and colours are not exposed in the inspector; set them with the set_water MCP tool described below.

WorldEnvironment#

DirectionalLight3D#

View Environment in the View menu hides the environment and sun while you work without changing them. The lighting theme chosen at creation (Default, Sunset, Night, Overcast, Dawn, Dungeon, or a project .tres template) is only the starting point for these values.

With AI (MCP)#

Terrain can be generated and shaped without the editor, on a working heightfield that is committed with a bake:

Every one that writes accepts dryRun: true to preview the result without changing anything; the read-only tools (read_terrain, sample_terrain, query_terrain_region) take no such argument.