13. FAQ

The terrain is not there when I press Play

• Check Terrain (Orrery) created an actor. There must be exactly one terrain actor in the level. A second one is refused with a warning in the log.
• Set the actor’s Source. An actor with no source is refused: the log warns Terrain of '<actor>' refused: it names no source asset. and Has Terrain stays false.
• Call Has Terrain on the subsystem. If it is false, search the log for LogOrreryTerrain warnings.
• Check the camera is over the terrain. Terrain starts at the origin of the source asset (default 0, 0), towards positive X and Y.

Get Ground Height Accurate returns NoData

The point is outside the terrain, or the world has no terrain. Check the location, in centimetres.

It returns Approximate or Pending

The full-resolution tile at that point is not loaded yet. Wait a moment, register an invoker (a point that keeps the ground around it loaded) near the point, or use Wait For Terrain Ground or Sample Ground Exact (Async). Use ExactOnly accuracy for gameplay that needs the exact answer.

My brush does nothing

Check, in order:

1. You are in Play. In the editor, the terrain is read-only.
2. Call Get Edit Access on the subsystem. It says why edits are refused: NoTerrain, ReadOnlyWorld, InBroadcast (you called from a ground-changed listener), Replica (this is a client), or Loading (the first tiles have not arrived).
3. Apply Brush returns Refused when the radius or strength is past the sculpt limits. Check Get Sculpt Limits.
4. Pending: the ground under the brush is still loading. The sculpt component queues those steps for you. Direct calls drop them.
5. With the brush tool: Default Input Component Class is Enhanced Input, and the brush kind in the HUD is the one you want.
6. The mouse is over the terrain in the viewport, and the player controller exists (with Mouse Cursor as the cursor source). The code does not test Show Mouse Cursor, but a hidden cursor gives the player nothing to aim with.

The brush tool draws a HUD but takes no keys

It could not find its input assets. The log says BrushTool: no input assets. Make sure the plugin content is cooked and present (/OrreryTerrain/Tools), or assign your own actions in the component.

A commit is refused

Read the Reason in the commit result.

• The ground under the feature is not loaded. Use the async nodes, or an invoker.
• You are in an editor world. Commit in Play.
• The plate’s polygon must be simple (not crossing itself) and have at least three points. Either winding works. The Reason reads invalid feature (fewer than 2 stations or 3 vertices, a self-intersecting polygon, stations over 2 m apart).

A save that will not load: different ground

The save does not load because it was made over different natural ground (another source asset, or a re-import with different data); the load result is NaturalMismatch. Load it over the same source.

Loading a save returns Corrupt

Either the file is damaged, or the reference does not match the file: you saved the slot again and kept an old reference. Always keep the newest reference.

My material shows up black or the terrain draws empty

• Assign the material in the editor, so the wrapper is made and saved. A cooked game cannot make it.
• If you set the RVT mode to Read, the material must write the runtime virtual texture, or the terrain draws empty. Use Auto unless you know you need Read.
• Check the log for a shader compile error. The wrapper needs the shader compiler, so wait for compilation to finish.

Lumen reflections or shadows look wrong near the terrain

Hardware ray tracing sees the near chunks within r.OrreryTerrain.RayTracing.Radius of the view, and the far field through one coarse grid. See Limits.

Moving the terrain actor

Moving the actor does not move the terrain. The origin is in the source asset (Origin_m).

Two terrains in one level

One per world. Put the second area in the same terrain, or in another level.

World Partition

Yes. With Use World Partition Sources on, the World Partition streaming sources drive residency. The terrain actor is always loaded. This needs World Partition streaming to be on in the map.

Landscape

It imports Landscape data (import). It does not replace the Landscape actor in your level, so hide or delete the Landscape after import.

Nanite meshes as ground

The terrain does not use Nanite. See Limits.

Terrain size

Up to 2048 tiles along one edge, each 127 cells wide, with a cell of 0.25 to 16 m. See Limits.

Multiplayer

Yes, on a listen server: the plugin replicates every edit itself, players who join late receive the edited ground, and you write no network code. It has been tested with four players on Windows. A dedicated server is not tested yet. See Multiplayer.

Custom brush textures

Yes. Make a Terrain Brush data asset from a texture or a single-band TIFF, or import a texture in the editor’s brush palette. A grey picture becomes a strength mask for the brushes or a height stamp. Textures are your own pictures, and the plugin’s starter set is generated, not taken from anywhere. See Texture brushes and stamps and Brushes and stamps.

Adding brushes at runtime

Yes. Register a brush asset with Register Brush, or raw pixels with Register Brush Mask From Pixels, on the terrain subsystem. Register again after every load: masks are not saved. A terrain holds 64 MiB of them. See Texture brushes and stamps and Limits.

Brushes in multiplayer

Yes. Masks, stamps and splats are sent to every player. A player’s own new mask is refused unless your game allows uploads, which are off by default. See Brush masks from players.

Splines deforming the terrain

Yes. A Terrain Spline Feature component turns a spline into a corridor (open spline) or a plate (closed spline) and rebuilds it in place. In the editor it follows your drag; in a game you call Rebuild when the edit ends. It is Experimental. See Live splines (runtime) and Live splines in the editor.

API units

Blueprint nodes and UOrreryTerrainLibrary use centimetres. Settings ending in _m use metres. Volumes are cubic metres. See Concepts.

Scripting from Python

Editor scripts can make a terrain, read the ground and place plates and corridors, with the Python Editor Script Plugin enabled. unreal.OrreryTerrainEditorLibrary holds the editor functions and unreal.OrreryTerrainLibrary the same queries a game uses. This script reads the cut and fill of a corridor, places it and undoes it:

import unreal

editor = unreal.OrreryTerrainEditorLibrary
world = editor.get_editor_world()

corridor = unreal.OrreryTerrainCorridorBP()
corridor.set_editor_property("points", [unreal.Vector(x, 200000.0, 0.0) for x in (100000.0, 150000.0, 200000.0, 250000.0)])
corridor.set_editor_property("formation_source", unreal.OrreryTerrainFormationSource.GROUND_PLUS_OFFSET)
corridor.set_editor_property("formation_offset", 0.0)
corridor.set_editor_property("half_width_left", 400.0)
corridor.set_editor_property("half_width_right", 400.0)

points = [unreal.Vector2D(x, 2000.0) for x in (1000.0, 1500.0, 2000.0, 2500.0)]
heights, exact = editor.sample_ground_heights(world, points)

works = unreal.OrreryTerrainLibrary.evaluate_corridor(world, corridor)
unreal.log("cut %.1f m3, fill %.1f m3" % (works.cut_volume, works.fill_volume))

placed = editor.place_corridor(world, corridor)
editor.undo_editor_edit(world)

• The corridor’s points are centimetres, as on every Blueprint node. sample_ground_heights takes metres.
• Load the ground first. evaluate_corridor answers valid false until the ground has loaded, and a script that calls it straight after making a terrain gets that. sample_ground_heights and place_corridor wait for the ground, for about a minute at most.
• approximate true means the figures still rest on some coarse ground. placed.earthworks carries the figures of the placed corridor. On a new 4 km procedural terrain (amplitude 40 m, wavelength 400 m, 1 m cell) this corridor evaluates to 375.5 m³ of cut and 191.7 m³ of fill over 14,731 m², and placing it reports the same volumes.
• The same script runs without a window: UnrealEditor-Cmd.exe <project> -ExecutePythonScript="<script>" -unattended -nosplash -nullrhi. The editor exits when the script returns.

Reporting a bug

See the support policy. Include the plugin version, the engine version, the platform, a minimal reproduction and the LogOrreryTerrain lines. The fields a bug report needs are listed in the bug form.