16. The editor mode

Open the mode

1. Choose Terrain (Orrery) in the Modes dropdown (or the Modes panel).
2. Pick a palette: Manage, Sculpt, Paint or Features. Each palette holds tools. Click a tool to start it; its settings appear in the Details panel.

Palette	Tools
Manage	New, and the Bake action
Sculpt	Sculpt, Smooth, Flatten, Stamp
Paint	Paint, Ground class, Holes
Features	Plate, Corridor, Features

Every tool except New works on the terrain of the level, so make one first.

Settings that belong to the mode and to the user, not to the project, are in the mode’s own settings object: whether the HUD shows (bShowHud), the colour of the preview ring (PreviewColor), how many segments it draws (PreviewSegments, 64) and Pause Grass During Strokes (off). Limits for your authors are in Project Settings > Orrery Terrain Editor (see Author limits).

Make a terrain: New

Manage > New makes a terrain actor and its source asset in one undoable step. It works in an empty level. Quick start walks through it with a procedural source, and Import covers heightmaps, GeoTIFFs and Landscapes. The fields:

Field	Default	Meaning
Source Kind	Procedural	Flat, Procedural, Heightmap, DEM or Landscape.
Size (km)	4	Side of the square, rounded up to whole tiles of 127 cells (128 posts) a side.
Cell (m)	1	Post spacing, 0.25 to 16.
Height (m)	0	Base height.
Amplitude (m), Wavelength (m), Octaves	40, 400, 4	The procedural hills.
Files, Decimate, Landscape	none	For the import kinds.
Asset Folder, Asset Name	/Game/Terrain, Terrain	Where the source asset goes.

The message line under the fields is an estimate and the reason a refusal would happen. For a 2 km procedural terrain it reads 16 x 16 tiles, 1.00 m cell, 2.03 km square, 4.13 km2; baked store about 2 MB, resident about 0.02 MB. Press Create Terrain. With a terrain already in the level, Create Terrain replaces its source instead of making a second terrain.

Brush tools: Sculpt, Smooth, Flatten

All three share the brush settings. Hold the mouse over the ground to see the ring; press and drag to stroke.

Setting	Default	Meaning
Radius (m)	20	Brush radius.
Strength	0.5	Fraction of the step height applied at the centre per step.
Step Height (m)	0.5	Height change of a full-strength step.
Falloff, Falloff Start	Smooth, 0 (Flatten: 0.5)	Edge shape, and the inner part of the radius at full strength.
Step Mode	Continuous	Continuous steps at Step Rate Hz (30); the other mode steps every Spacing (0.25) of the radius along the path.

• Sculpt raises the ground; hold Shift to lower it. The HUD reads, for example, Sculpt (raise) radius 20.0 m strength 0.50 falloff Smooth 0.00.
• Smooth averages the ground under the brush.
• Flatten pulls the ground toward a target height. Flatten Target is Stroke Start (the height under the cursor when you press, the default), Each Dab (the height under each step) or Fixed (Flatten Height (m); Ctrl+click on the ground copies the height under the cursor into it). Flatten Direction can limit it to raising or lowering. The ground moves toward the target step by step, not at once, and the rim follows it smoothly. The HUD shows the target, for example to -12.48 m (Stroke Start).

Keys, in all three tools: [ and ] change the radius, Ctrl+[ and Ctrl+] the strength, Ctrl+Shift+[ and ] the falloff start.

Undo. Each stroke is one editor transaction: Ctrl+Z restores the ground, and the state hash with it.

The brushes obey the author limits: the radius and the step height cannot go past Max Radius and Max Step.

Paint tools: Paint, Ground class, Holes

These use the same brush ring and the same keys. For Paint, Ctrl+[ and ] change the opacity instead of the strength.

• Paint paints a material layer. Pick Layer (a name from the terrain’s layer set, or Layer N) and Opacity. Painting another layer replaces the lightest of the four layers at each post. The HUD reads Paint 'Layer 0' radius … opacity 1.00 …. See Materials and layers.
• Ground class paints the geology class, 0 to 7 (the class selects physics and sound in your game; it does not change the look). Fill Class sets the class a stroke fills with. It is on unless Paint Ground Class is off in the author limits.
• Holes cuts holes in the ground, for caves and tunnel mouths; Shift fills them again. Holes are allowed by default. If you switch Allow Holes off, the tool refuses and its message names the setting.

A terrain is one heightfield, so a hole does not make a cave: your game places the mesh that fills it (Limits).

Brushes and stamps

A brush mask gives a tool a shape other than the round ring: a rock face, a dune, a crater. Masks are Terrain Brush assets (Texture brushes and stamps); the mode registers a mask with the terrain when a stroke or a stamp first uses it.

The palette. The brush tools, the paint tools and the Stamp tool show a row of thumbnails above their Brush Mask settings. Disc (no mask, the round brush) comes first, then the baked brushes of the brush sets in the plugin’s Brushes folder, then those of the sets listed in Project Settings > Orrery Terrain Editor > Brush Sets, each brush once. A brush you picked that is in no set comes last. Click a thumbnail to pick it; the angle takes the brush’s own Default Angle. Each tool keeps its pick until you close the editor; it is not saved.

Setting	Default	Meaning
Angle	0	The mask’s turn, degrees from +X toward +Y.
Rotation Mode	Fixed	Fixed, Follow Stroke (each dab turns with the direction of travel) or Random (each dab turns up to Jitter, 180 degrees, either way; the same on every machine). Not in the Stamp tool.
Mirror	off	Flips the mask.
Footprint	Disc	Disc clips the mask to the ring; Square uses its whole square.

Keys, with a mask picked: , and . turn it by 15 degrees, Ctrl+mouse wheel by 5. Picking a mask switches a Continuous brush to Spacing, so the dabs fall evenly along the path. The ring shows the mask’s 50 % outline (and the square, for a Square footprint) with a tick toward its +X, and the HUD names it, for example Mask BM_Rock angle 30 deg Fixed.

Import. Select a texture in the Content Browser, set Channel, Invert, Side (0 keeps the default) and 16-bit under Brush Mask Import, and click Import selected texture. The mode bakes a brush asset BM_<texture> beside the texture (or in /Game/TerrainBrushes for a texture outside your project’s content) and picks it. Save it to keep it. In the Stamp tool the asset is a Height mask; elsewhere a Strength mask.

Stamp. The Stamp tool, in the Sculpt palette, places the picked height mask once per click: a mountain, a crater, a mesa.

Setting	Default	Meaning
Radius (m)	250	Half the mask’s side, 1 to 1000.
Height (m)	200	A white sample’s height over the base; negative digs.
Blend	Max	How the shape meets the ground: Add, Max (only raises), Min (only lowers) or Blend.
Base, Base Height (m)	Ground at centre	The height the shape stands on: the ground under the centre, or a fixed height.
Falloff, Falloff Start	Smooth, 0.8	The edge, as for the brushes.

• Hold the mouse over the ground: a translucent surface, lit by the scene’s sun, shows the ground the stamp would make, cyan where it raises the ground and orange where it cuts. It fades out where the stamp changes the ground by less than a few decimetres, so unchanged ground stays visible. A 65 x 65 wire grid outlines it, in cyan.
• Where the stamp cuts below today’s ground, the cut shows through the ground in orange: the surface in stripes and the wire grid in translucent lines, both faint for a shallow cut and full strength from 30 cm deep. What the stamp leaves on or above the ground looks as before. A point counts as cut where the stamp lowers that post; a cut of under half a centimetre is marked, though the stored ground keeps its height.
• The surface has a point on every post of the terrain’s edit cell, or on every 2nd, 4th or 8th post of a big stamp, to stay within 65,536 points. A 2 km stamp takes every 8th post at 1 m cells and every 4th at 2 m cells. Each point is the height the stamp writes to that post.
• The surface and the wire grid are built together on a worker thread, from one reading of the ground, and only when the stamp or the ground changes; while you drag, they trail the cursor by one build. The HUD shows the costs, for example Preview 65 x 65 worker 1.06 ms draw 0.25 ms cut 0 and Surface 251 x 252 every 8 posts, 8.0 m worker 2.8 ms game 0.00 ms for a 2 km stamp at 1 m cells. Preview: the wire grid’s part of the build, the editor’s game thread drawing the grid in the last frame, and the grid’s points that cut. Surface: the whole build, on a worker thread, and what the surface cost the game thread in that frame. The surface disappears when you click, and comes back when you move or change the stamp; the wire grid stays and shows the next stamp over the stamped ground.
• The console variable Orrery.Terrain.Stamp.PreviewPoints sets the most points (65536 by default); 0 shows the wire grid alone.
• Click to stamp. Press and drag first to size it: the stamp stays on the press, its radius is the drag’s length and its angle the drag’s direction. Esc during the drag cancels it and restores the radius and angle. [ and ] change the radius, , . and Ctrl+wheel the angle.
• Over ground that is still loading, the stamp waits (the HUD says so) and applies once, whole, when the ground under all of it is in; it gives up after 60 s, and Esc drops it.
• Each stamp is one undo step. A stamp is the same as the runtime brush tool’s Stamp At with the same mask, angle, radius, height and blend.
• The Details panel warns when the mask is too coarse for its stamp: 8 bits a sample (or an 8-bit source texture) climbs in terraces, and a sample wider than 4 m on the ground shows facets. Re-import at 16 bits, or use a larger Side.

Starter brushes

The plugin ships one brush set, TerrainStarterBrushes, in its Brushes folder, so the palette shows it with no setup. Every image in it was generated by a script from noise and closed-form shapes; none comes from a third-party heightmap or texture.

Six strength masks (256 x 256, 8 bits; the radius is how wide a brush must be for the mask’s detail to show on a 1 m grid) scale the Raise, Lower, Smooth, Flatten and Paint tools per ground point. White is full strength:

Brush	Look	Use it for	Radius
SoftNoise	Soft cloudy blobs	Natural-looking Raise and Lower, soft paint	40 m
RockyBreakup	Ridged, broken rock	Craggy faces with Raise or Lower	30 m
Cracks	A web of thin cracks	Fissures with Lower, dry-mud lines with Paint	50 m
Speckle	Scattered soft dots	Pebbles, tufts, scatter paint	40 m
HardStone	One hard-edged faceted stone	Boulders and blocks with Raise	25 m
Streaks	Runnels along the mask’s +Y	Erosion gullies, rain wash, scree (turn it with Angle)	50 m

Six height stamps (1024 x 1024, 16 bits) are for the Stamp tool. The mask’s peak is exactly white, so Height is the peak height over the base. Picking one in the Stamp tool sets Radius (the brush asset’s Default Radius, limited to 1 to 1000 m), Height and Blend to the values in the table (Suggested Height and Suggested Blend; a brush of your own can carry them too). Picking sets them once; you can change them afterwards, and they stay until you pick another brush. The radius is a good first size:

Brush	Look	Radius	Height	Blend
Crater	Raised rim, ejecta apron, low floor with a small central peak	60 m	6 m	Max
Volcano	Gullied cone with a summit caldera	400 m	250 m	Max
Mesa	Flat top, cliffs and a talus apron, plus a small butte	250 m	80 m	Max
Ridge	A meandering ridge along the mask’s +X with a low skirt	300 m	120 m	Max
Dunes	Sinuous crescent dunes, a gentle windward and a steep lee side	200 m	25 m	Max
Massif	A rounded massif: one broad summit with five shoulders	500 m	150 m	Max

The twelve masks hold 12.4 MiB on disk and 17 MiB in a terrain’s mask registry (of its 64 MiB budget) when all of them are registered; a mask is registered only when you first use it. A stamp is a shape, not a dig: for a pit, use the stamp with a negative Height and the Min blend.

Plates

A plate is a flat pad with sloping sides. Features > Plate:

1. Click on the ground to add the corners of the pad, in order. Backspace removes the last corner, Esc cancels. A pad needs at least three corners. The HUD says Plate: 4 vertices. Click adds one, Backspace takes it back, Enter places, Esc cancels.
2. Set the height. Height From is Average (the average ground under the pad), First Vertex, Highest, Lowest or Fixed (Top Height (m)); Height Offset (m) raises or lowers the result.
3. Set Grade X and Grade Y (percent, plus or minus 50, for a sloping top) and Fill HV and Cut HV (the batters, 1.5 by default, 0.1 to 10).
4. Watch the HUD while you work. It shows the top height and grade, the slopes, and the earthworks: Cut … m3, fill … m3, footprint … m2. The line says approximate while the ground under the pad is still loading. Where the batters need retaining walls it adds the count of wall runs and the height of the highest.
5. Press Enter. The plate is placed as one undoable step. Over ground that is still loading, the tool waits for the tiles and then places it; leaving the tool cancels the wait.

Corridors

A corridor is a road, rail bed or canal bank along a line. Features > Corridor:

• By hand. With Path Two Points, click the start and the end on the ground. The HUD shows the length and stations: 126.5 m, 128 stations, width 3.0 + 3.0 m, crossfall 0.0%. Enter places the corridor, Esc drops the line, and a click after placing starts a new one.
• Along a spline. Select an actor with a Spline component (a road actor from your game, a spline you placed) and press Use Selected Spline in the tool’s details. The tool takes the first spline of the first selected actor, samples it at the station spacing and shows the corridor. It tells you when no selected actor has a spline. Press Enter to place.
• Settings. Half Width Left and Half Width Right (3 m each by default), Crossfall (%), Station Spacing (m) (1, from 0.1 to 1.99), Fill HV and Cut HV, and Keep-out runs (a bridge, a viaduct or a tunnel bore with an optional opening, as in plates and corridors). Formation Source is From Points (the height of the points) or Ground Plus Offset (the ground plus Formation Offset (m)).

Like a plate, a corridor over ground still loading waits for it. The corridor is a feature: it sits on top of the natural ground and your sculpting, can be selected later, and saves and loads with the terrain.

The feature list

Features > Features lists the plates and corridors placed in this level. Click a footprint in the viewport, or pick one in the list, to select it. The tool then shows the feature’s settings; change them and press Apply Changes to rebuild it, or Delete (or Remove) to remove it. Esc clears the selection. The HUD starts with Features: 1 authored. and Delete with nothing selected answers Refused: nothing selected. Like placing, removing over ground that is still loading waits for the tiles.

Live splines in the editor

A Terrain Spline Feature component makes a spline drive a feature: a corridor along an open spline, a plate inside a closed one. Add it to an actor with a Spline component (Add > Terrain Spline Feature in the details panel). Its feature is built when you add it, and from then on it follows the spline. This is experimental in v1.0: it relies on an engine notification that is itself experimental.

• Drag, then release. Edit the spline as usual: drag a point or a tangent, or move the actor. While you drag, the viewport previews the feature (yellow edges, a magenta centreline) and the HUD shows Spline feature: editing; the ground changes on release. and Preview: cut 37632 m3, fill 5534 m3. The ground changes once, when you release. The preview is refreshed at most every 0.1 s; for a long feature, at most every four times as long as one preview takes.
• One undo. The ground change is stored in the edit’s own undo step, so one Undo takes back the spline and the ground together, and Redo puts both back. Undo and redo never build anything.
• Over ground still loading. The change waits for its ground, the HUD says Ground loading: the spline feature waits for its ground and lands as its own transaction. and the component’s state is Pending. It lands as its own undo step: the first Undo then takes back the ground, the second the spline edit. A newer edit while one waits replaces it.
• Refused. A shape the kind cannot build (a closed spline for a corridor, an open or self-crossing one for a plate) keeps your edit: the HUD shows Refused: ..., a notification names the reason, and the feature stays as it was until an edit is accepted.
• Delete. Deleting the actor, the component or its spline removes the feature in the same undo step; Undo restores both, linked again.
• Copies. Duplicate (Ctrl+D, or Alt and drag) and copy and paste give the copy its own feature; the original keeps its own. One Undo takes back the copy and its feature.
• Blueprint actors. A construction script that runs again (after a property change, or while you move the actor) keeps the link to the feature. Moving the actor moves its feature when you release it.

In the component’s details, Rebuild builds the feature from the spline now, Remove removes it and Select in Features Tool opens the feature list with it selected. Switch Live In Editor off and only Rebuild builds. The feature list shows a spline feature as #3 Spline: Road, corridor 186.4 m (the id, the actor, the kind and its length). Its settings belong to the component and are read-only in the list. Select Actor selects the actor, and Delete removes the feature. The component then reports Missing and builds nothing until you edit the spline or press Rebuild.

When a level loads with spline features whose features are gone from the terrain (removed elsewhere, or the level saved apart from its terrain), a notification says how many and offers Rebuild all. Loading never builds anything by itself.

Play in Editor never edits the editor’s ground: spline features in the play world follow the runtime rules. In a Level Instance they build only while you edit that Level Instance.

Bake

Editor edits do not change the source asset. They are kept in an authoring layer beside the map (the sculpt, the paint, the ground class and the features), and they are undoable as editor transactions. A cooked game does not carry the authoring layer, so you bake it.

Bake composes the layer into a new tile store beside the map, points the terrain at it, clears the undo history and leaves the old source and the layer in place (the layer asset gets a _PreBake_<n> copy). It is available only while something is unbaked. Start it from the Bake action in the Manage palette or the Bake terrain button in the terrain actor’s details. Both ask you to confirm.

What to expect, from a bake of a 2 km terrain with a plate and a corridor: 256 tiles and 87 mip tiles, a 2.2 MB store <Map>_TerrainStore_1, and heights that equal those before the bake at the sample points. The bake reports the largest difference (here 5 mm) and warns where a retaining wall becomes a step in the ground. The natural ground changes: a saved game or a multiplayer join made over the old ground is refused (the save does not load, the client cannot join), so bake before you ship a build and before you start saving test games.

With Bake On Save (project settings) every save bakes. It is slow on large maps.

Bake on a build machine

The commandlet OrreryTerrainBake bakes maps without opening the editor window:

UnrealEditor-Cmd.exe <Project>.uproject -run=OrreryTerrainBake -Map=/Game/Maps/Level1/ -unattended

• -Map=<name> is the short name of a map (a folder path ending in / takes every map in it). Several maps are joined by + or ,.
• -Check bakes nothing: it exits 1 when any map is unbaked (a release gate) and 0 when all are baked. A usage error exits 2.
• -MaxResidentTiles=N and -Workers=N limit the memory and the threads of a bake.
• The last line is a summary: OrreryTerrainBake: baked N map(s): U unbaked, B baked, F failure(s) -> ok (checked instead of baked with -Check; FAILED when anything failed).

Author limits and settings

Project Settings > Orrery Terrain Editor (stored in the project, so your team shares it):

Setting	Default	Meaning
Unbaked Cook	Error	What the cook logs for a map with an unbaked layer: Error, Warning or Off.
Authoring Folder, Bake Folder	empty (beside the map)	Where the authoring assets and the baked stores go.
Max Radius (m)	2000	Largest brush radius an author may use.
Max Step (m)	10	Largest height change of one step.
Paint Ground Class	on	Authors may paint the ground class.
Allow Holes	on	Authors may cut holes.
Bake On Save	off	Bake on every save.
Follow Edits	on	Placed foliage, tagged meshes and ground-follow actors follow the mode’s edits in the same undo step (chapter 15).

Drive the mode from Python

For tests and build scripts, unreal.OrreryTerrainEditorLibrary runs the same code as the tools without a viewport. Among its functions: new_terrain, apply_editor_stroke, place_plate, place_corridor, undo_editor_edit, bake_authoring, has_unbaked_authoring, get_state_hash and sample_ground_heights. It can also start the mode and its tools (activate_terrain_mode, start_tool, click_active_tool, drag_active_tool, press_tool_key, get_active_tool_hud), pick a mask (set_active_brush_mask) and set and follow a stamp (configure_active_stamp, is_stamp_pending). A stroke whose Falloff Start is -1 uses the tool’s own default.

Add a brush target (C++) Experimental

A module of yours can add something the brush edits, such as a snow-depth layer, and receive the brush strokes. Implement IOrreryTerrainBrushTargetV2 (OrreryTerrainEdExtensionV2.h) and register it with FOrreryTerrainEdRegistry::RegisterBrushTargetV2 in your module’s startup, or return it from an IOrreryTerrainEdExtensionV2 modular feature. Then tick it in the editor: the details panel of the Sculpt, Smooth, Flatten, Paint and Stamp tools has an Extension Targets section listing every registered target, V1 and V2, by display name and id (IOrreryTerrainBrushTargetV2::GetDisplayName; a V1 target shows its id). Tick Also edit a target and that tool drives it beside the ground: the ground is always edited, and nothing is ticked at first. Your target then gets every dab of each stroke, or the stamp as one dab, and its undo record joins the stroke’s own, so one undo takes back the ground and your layer together. The ticks last for the editor session and are never saved; a target that unregisters drops out of the next stroke. Code can also give a tool ids with SetExtensionTargets.

• Each dab is a FOrreryTerrainBrushDabV2: position, radius, strength, time and invert as before, plus the mask’s hash and baked samples, this dab’s resolved angle, mirror, footprint, aspect ratio and the bicubic flag. A stamp is one dab with bStamp and StampHeight_m.
• SampleMask(Point_m) returns the mask at a world point exactly as the sculpt kernel reads it: the same rotation, sampler and mip level. Use it, rather than your own sampler, so your layer has the shape the ground has. It answers 0 off the mask; SampleMaskQ16 answers -1 there, and 65536 is full strength. The falloff curve is yours.
• A Paint tool stroke with a splat sends your V2 target one dab per used channel of the splat, in channel order, each with that channel’s mask: SplatStep (0, 1, …), SplatChannel (0 red to 3 alpha) and PaintLayer say which; a plain dab has -1 in all three.
• A target built on IOrreryTerrainBrushTarget (V1, OrreryTerrainEdExtensionV1.h) keeps working unchanged. It receives the plain dab with no mask, as it did before (one per splat dab): a masked brush looks like a round brush to it.
• One id is one target: the registry refuses a V2 target whose id a V1 target holds, and the other way round.
• The V2 header is experimental in this release: it may change in a minor version, with a changelog line.

Not in the mode

• There is no Import tool and no Layers or Settings palette entry: use New for imports, the terrain actor for the layer set, and the project settings above.
• The mode edits one terrain per level, and it does not edit a Landscape.
• The mode does not draw or edit a mask: make the picture in a paint program and import it.