7. Tutorial: materials and layers

The default material

If you leave the actor’s Material empty, the heightfield renderer draws the plugin’s default material, MI_TerrainDefault_W.

It gives you a starter look with no setup:

• Nine ground textures (grass, soil, rock, gravel, meadow, sand, forest floor, snow, cobblestone) in four texture arrays, one slice per paint layer, with colour, normal, roughness and height maps.
• Automatic ground. Paint layer 0 (grass) is not flat grass. Rules mix meadow, bare soil, scree, rock and snow by slope and altitude, with noise. Steep ground becomes rock without anyone painting it.
• Painted layers on top of that, blended by height so stones show through grass.
• Side projection for rock, so cliffs do not stretch.
• Large-scale colour variation against visible tiling.
• A far-distance blend that fades fine detail into a calmer average.
• A runtime virtual texture for the distant ground.

A second version of the material, MI_TerrainDefault_Displaced_W, adds real surface displacement near the camera. The renderer picks it when sub-post displacement is on. See Performance and quality.

The ground textures are CC0, from public texture libraries. Licence notes are in the third-party notices.

Use your own material

1. Make a material (or material instance) for a surface. It can be as simple as a coloured surface with a texture.
2. Select the terrain actor. Under Terrain, set Material.
3. The editor makes a wrapper for you: an instance of your material that the terrain’s shaders can use. It is saved next to the terrain asset, in a TerrainWrappers folder, and named <your material>_W. It follows every change you make to your material.
4. Save all. The wrapper is part of your content and cooks with the game.

Rules:

• A cooked game cannot create wrappers. Always assign the material in the editor and save the wrapper.
• The mesh tier accepts any material without a wrapper. The heightfield tier needs the wrapper.
• Wrappers can also be made in bulk from Blueprint or Python with Wrap Materials, or one at a time with Wrap Material. Find Wrapper looks one up without creating it.

Your own look with the plugin’s layer blend

To keep the paint layers but change the textures, make a copy of M_TerrainDefault and change the texture arrays and the parameters of the MF_TerrainLayers function. Its parameters include the auto rules (AutoRule0_Slope to AutoRule4_Noise) and the blend strength (LayerBlend). Slice N of each array is paint layer N.

Values per layer (tile size in metres, displacement in cm, the height map’s mean, side projection on or off) are not material parameters. They are rows of one texture, T_TerrainLayerTable: 256 texels wide, one texel high, RGBA32F, one row per layer id. Row N holds layer N: R tile size in metres, G displacement in cm (0 is none), B the mean of the layer’s height map (0 to 1), A 1 where the layer projects onto steep sides. The material reads it through the LayerTable texture parameter.

The plugin’s default table is built from our layer list when we make the default material. To change a value for your own layers, build a new table and point your copy’s LayerTable parameter at it. From Python:

import unreal

rows = [unreal.LinearColor(1.0, 0.0, 0.5, 0.0) for _ in range(256)]   # tile m, displacement cm, height mean, side projection
rows[2] = unreal.LinearColor(4.0, 0.0, 0.5, 1.0)                     # layer 2: 4 m tiles, projected onto cliffs
tex = unreal.OrreryTerrainMaterialLibrary.make_layer_table("/Game/Terrain/T_MyLayerTable", rows)

MakeLayerTable returns null when you pass more than 256 rows. Missing rows are zero. The texture is not saved: save it, then set it as the LayerTable parameter of your material instance.

Paint layers

A paint layer id is 8 bits: layers are numbered 0 to 255, and a layer set names up to 256 of them. The default material ships nine ground textures, so its arrays have nine slices.

Each post holds the weight of up to four layers. Painting a fifth layer replaces the lightest of the four. Layer 0 is the natural ground the rules draw on, so you rarely paint it.

Name them with a layer set

1. In the Content Browser, Add > Miscellaneous > Data Asset, pick Terrain Layer Set, and name it LS_Terrain.
2. Open it. Add one entry per layer, in order. Entry N is paint layer N.
3. For each entry set:
   • Name: unique in the set. This is what code looks up.
   • Display Name: what a palette shows.
   • Slice: which slice of the material’s texture arrays the layer draws, 0 to 255.
   • Preview Color: for palettes and minimaps.
   • Grass: see Grass.

The layer set serves names and grass. Point the terrain actor’s Layer Set property at it to turn the grass on. The brush tool component still takes its layer names from its own Paint Layer Names.

Paint from the brush tool

In the brush tool component, add Paint to Brush Kinds and fill Paint Layer Names in the same order as your layers. Press B until the HUD shows Paint, press N to pick the layer, and drag. See Sculpt at runtime.

Paint from code or Blueprint

Set the brush to Paint, choose Paint Layer (0 to 255) and Paint Opacity (0 to 1), and apply it in a stroke as in the sculpt chapter.

Find Paint Layer turns a name into an index:

1. Hold a reference to your LS_Terrain asset.
2. Call Find Paint Layer with the layer set and a name such as Rock. It returns the index, or -1.

Read the paint under a point

1. Call Sample Ground with a location. In Fields, tick Paint.
2. From the returned sample, call Get Dominant Paint Layer for the heaviest layer, or Get Paint Weight for one layer’s weight (0 to 1).

Use this for footsteps, tyre sounds and gameplay rules (“no building on rock”). Tick Ground Class in Fields and the sample also gives a Ground Class, a Hole flag and a Physical Material.

Painted layers show on the near terrain. The far field draws only the automatic rules.

The auto rules colour the ground but are not part of the painted data. They are not in the paint weights you read.

Check it worked

1. Set the actor’s Material to a plain coloured material. Look at the Content Browser: a TerrainWrappers folder with <name>_W appears next to the terrain asset.
2. Clear the Material. The terrain returns to the default look.
3. In Play, paint a patch with layer 2. Call Sample Ground with Paint selected at its centre. Get Dominant Paint Layer returns 2.