HPL3/SOMA/Level Design/Creating Terrain

{​{shortPageTitle}}

A terrain is an editable height-mapped surface created inside the SOMA Level Editor. It is useful for large continuous ground such as a seabed or an outdoor landscape. Terrain has separate tools for shaping its height map, painting materials, adding terrain decals, and placing undergrowth.

{​{note|Create terrain in a map inside your mod, not in one of SOMA's original maps. Creating a new terrain cannot be undone and clears the editor's undo history. Save the map before opening the creation dialog.}}

Before you start

1. Open your mod's map in LevelEditor.exe. See Edit Your First Map if the mod-aware editor and save/reopen workflow have not already been tested.
2. Save a backup of the map and all of its adjacent .hpm_* files.
3. Select Terrain EditMode on the Level Editor toolbar.

Every inspected shipped SOMA map has a terrain track named <map name>.hpm_Terrain. A shipped map without terrain keeps this track with Active="false"; an active terrain definition records Active="true" and its setup data.

Create the terrain

1. In Terrain EditMode, open Terrain Setup and choose Create Terrain.
2. Set HeightMap Size, Unit Size, Max Height, Geometry Patch Size, and Texture Patch Size. The dialog also displays the resulting terrain size and texel density.
3. Review the warning, then click Create. Creation cannot be undone and clears the undo stack.
4. Save the map before doing detailed sculpting or painting.

The setup values determine the terrain's resolution, scale, vertical range, and patch layout. Choose them before investing time in editing: creating another terrain is a destructive replacement rather than an ordinary undoable edit.

Setting	Purpose and verified constraints
HeightMap Size	Sets the stored height-map resolution. SOMA's active shipped terrains use either 512 or 1024. The engine rejects a height map that is smaller than either patch size and rejects a height map whose width and height differ.
Unit Size	Controls the terrain's world scale and therefore affects the size and texel-density values shown by the dialog. Nine of the ten inspected active SOMA terrains use 1; one uses 0.5. The SOMA outdoor-performance guide recommends 1 or higher for outdoor terrain.
Max Height	Sets the terrain's available vertical range. This is project-dependent: shipped values range from 15 to 512, so there is no single campaign-wide value to copy.
Geometry Patch Size	Sets the geometry patch size. It must be a power of two and cannot be larger than the height map. Active shipped SOMA terrains use 16 or 32.
Texture Patch Size	Sets the texture patch size. It must be a power of two, cannot be smaller than the geometry patch size, and cannot be larger than the height map. Every inspected active SOMA terrain uses the same value for its geometry and texture patch sizes, matching the outdoor-performance guide.

The values above describe shipped SOMA data and executable validation messages; they are not universal presets. A small test terrain can follow the compact 05_01_phi_inside example below, but its dimensions and height range still need to fit the intended map.

Shape the height map

Open the HeightMap terrain submode. It provides three brush types:

• Raise/Lower adds or subtracts height where the brush is applied.
• Flatten moves the affected area toward a chosen height.
• Smooth reduces sharp height changes.

The brush controls exposed by the SOMA editor include Inner Radius, Outer Radius, Falloff Exp, optional brush noise, octave count, and noise frequency. Work from broad forms to small corrections: establish the main silhouette with a large brush, flatten areas that need deliberate level ground, and smooth unwanted spikes last.

The HeightMap tools also provide Import, Export, and Generate. When importing, use a square, uncompressed source of an appropriate resolution; the engine reports errors for compressed bitmaps and non-square height maps. Keep a copy of an external source image because the map's working terrain height map is saved as a DDS sidecar.

Give the terrain a material

Switch to the terrain's Texture submode after the surface exists.

1. Assign a Base material file. This covers terrain that has not been painted by a blend-layer material.
2. Adjust its Tile amount, HM scale, Fade start, and three-component Detail texture amount only as required by the material and scene.
3. Set Specular Power for the terrain.
4. Add a blend layer if more surface materials are needed. A blend layer contains four material slots; select the target layer and sublayer before painting.
5. Assign terrain .mat files to the required slots, then use the Add and Erase brushes to edit their coverage.
6. Optionally configure up to three detail textures and their fade range. Cliff diffuse/normal textures and undergrowth can be added later when the basic terrain has been verified.

Use materials whose type is suitable for terrain. Material paths and painted masks are separate data: the paths are recorded in .hpm_Terrain, while each saved blend layer has a corresponding DDS mask.

Save and verify

1. Save the map, close it, and reopen it in the Level Editor.
2. Confirm that the terrain is still active, has the expected dimensions, and retains a visible base material.
3. Make one obvious Raise/Lower edit, save and reopen again, and confirm that the shape persists.
4. If a blend layer was added, paint a clearly visible test patch and verify that it also persists.
5. Launch the mod and inspect the terrain from the player's reachable area. Check collision, slopes, material scale, and the transition between terrain and surrounding meshes.

A saved terrain uses files beside the main .hpm map:

File	Stored content
<map>.hpm_Terrain	Terrain setup, material paths, detail-texture settings, blend-layer definitions, terrain decals, and undergrowth records.
<map>.hpm_Terrain_heightmap.dds	The active terrain's height-map data.
<map>.hpm_Terrain_blendlayer_N.dds	Painted data for blend layer N. There is one such sidecar for each saved blend layer.

Keep these files together when copying, renaming, packaging, or restoring the map. Editing only the main .hpm file does not preserve the terrain.

Shipped SOMA example

The comparatively small terrain in maps/chapter05/05_01_phi_inside/05_01_phi_inside.hpm_Terrain demonstrates a complete active terrain without cliff textures or undergrowth:

Setting	Stock value
HeightMap Size	512
Unit Size	1
Max Height	15
Geometry / Texture Patch Size	16 / 16
Base material	textures/terrain/sand/sand_flat.mat
Blend layers / material slots	1 / 4

Larger outdoor campaign terrains commonly use a height-map size of 1024 and matching patch sizes of 32, but their maximum heights and materials vary substantially. Treat shipped maps as structural examples rather than templates whose numbers should be copied unchanged.

Troubleshooting

• The terrain is absent after reopening: confirm that <map>.hpm_Terrain is writable, remains beside the main map, and contains Active="true".
• The terrain is untextured or uses a fallback: check the base terrain material path and ensure the material and all referenced textures are included by the mod's resources configuration.
• The editor rejects the patch settings: both patch sizes must be powers of two, the texture patch cannot be smaller than the geometry patch, and neither can exceed the height-map size.
• An imported height map fails: use a square, uncompressed image. Check that its resolution is not below either patch size.
• Paint disappears when the map is moved or packaged: include every _blendlayer_N.dds file with the map.
• The terrain is too expensive: begin with the terrain optimization checklist. In particular, use matching geometry and texture patch sizes and avoid unnecessarily small unit sizes.

See also

• Terrain Height Map
• Terrain Texturing
• Undergrowth
• Outdoor Level Performance