Skip to content
Orbdale

Orbdale Terrain · OrbdaleTerrain module · class

UOrbdaleTerrainSubsystem

The terrain of one world: owns its FTerrainWorld and everything that keeps the engine in step with it (Tier 2.5 owner + Tier 3 shell).

Declaration

UCLASS()
class UOrbdaleTerrainSubsystem : public UTickableWorldSubsystem
Header
#include "OrbdaleTerrainSubsystem.h"
Module
PublicDependencyModuleNames.Add("OrbdaleTerrain"); in your module’s Build.cs.
Stability
Stable: changes within a major version only add.
Thread
Every member function is game thread unless it says otherwise.
Derives from
UTickableWorldSubsystem
Blueprint
“Orbdale Terrain Subsystem”, a Blueprint type

Description

Owns (none of it reflected, so the GC never walks ground data):

  • the Tier-1 FTerrainWorld, built from the host actor's source asset at CreateTerrain;

  • the streamer: streaming sources and invokers in, base-tile loads run on the UE task system, completions handed back on the game thread (the world only emits requests);

  • the chunk manager: one UOrbdaleTerrainCollisionComponent per resident edit tile, rebuilt and swapped in place, and the per-chunk heights the renderer consumes;

  • the ground provider, registered as the modular features Orbdale.Ground.V3 and V2 while the terrain exists and its world has precedence (see FGroundFeatureRegistration).

Worlds. Game, PIE and Editor worlds. An editor world's terrain renders and collides but is read-only: every edit, sculpt and load call is refused there, and its contract provider refuses edits too (FReadOnlyGround). Every Game and PIE world, terrain or not, suspends the editor world's provider registration while it lives.

Threading. Every member function is game thread unless it says otherwise. Readers on other threads (Mass, the contract's consumers) take an FGroundQuery on the game thread with AcquireQuery and pass it down; the query is lock-free and consistent per snapshot.

Units. The Blueprint API speaks Unreal units (cm, world FVector), converted once through OrbdaleTerrain::Units. The C++ edit API speaks Tier-1 types (metres, millimetres relative to the terrain origin).

Events. Every publish of the world (commit, undo, sculpt step, streaming, load) first marks the chunks dirty, then broadcasts OnGroundChanged and OnGroundChangedBP. A listener may read the ground but not edit it: edits from inside a broadcast are refused, and DestroyTerrain from inside one is deferred to the next tick.

Note.

One terrain per world. A second CreateTerrain is refused with a warning.

Functions

  • UOrbdaleTerrainSubsystem (2 overloads)
  • Initialize
  • Deinitialize

    Destroys the terrain if it still exists, then ends this world's game-world claim.

  • Tick

    Streaming, load completion, chunk rebuilds and swaps, in that order.

  • GetStatId
  • IsTickable

    Ticks only while a terrain exists (or a deferred destroy waits).

  • IsTickableInEditor

    Editor worlds stream and rebuild their read-only terrain too.

  • IsTickableWhenPaused

    Streaming follows the cameras while the game is paused.

  • CreateTerrain

    Create the terrain from a host actor's source, settings and material.

  • DestroyTerrain

    Destroy the terrain.

  • HasTerrainBlueprint

    True when this world has a terrain.

  • GetTerrainActorBlueprint

    The actor that hosts the terrain, or null without one.

  • GetTerrainSerial

    A number this process gives each terrain a subsystem creates, never reused: it changes with every re-create, so an undo record holding tokens of this terrain's features (the editor's feature change) can tell that the features it names are gone.

  • IsReadOnlyBlueprint

    True when the terrain refuses edits by default: the terrain of an editor world.

  • GetEditAccessBlueprint

    Whether sculpting and painting would be accepted now, and if not why: for a UI that greys its tools out.

  • GetEditAccessAtBlueprint

    GetEditAccess for a brush over one circle: whether a sculpt or paint step there would be applied now rather than answer Pending.

  • GetFeatureEditAccessBlueprint

    GetEditAccess for committing or removing a feature owned by OwnerDomain.

  • IsGroundProviderRegisteredBlueprint

    True while this terrain's provider is the one registered as Orbdale.Ground.V3 (and V2).

  • IsGroundProviderSuspended

    True while this editor terrain's provider waits for game worlds to end (see FGroundFeatureRegistration).

  • GetNaturalSource

    The natural ground the world reads, or null.

  • GetStreamingSources

    The streaming sources the residency was last computed from: world metres (FStreamingSource::Position), each with its radius, in the order the streamer gathered them (World Partition or player views, then invokers).

  • AcquireQuery

    The current snapshot.

  • GetGroundHandle

    The terrain's any-thread handle (FGroundHandle): keep it in a task, a PCG worker or an extension's simulation and acquire queries there without a hop to the game thread.

  • GetGroundHeightBlueprint

    Ground height at a world position, read from one snapshot, lock-free.

  • RaycastGroundBlueprint

    Analytic ray against the ground: no physics scene, never hits anything but ground.

  • GetRevisionBlueprint

    Revision of the published ground; bumps once per published change.

  • GetLastEditRevisionBlueprint

    Revision of the last published change to the ground's truth: an edit, an undo or redo, a sculpt or a load.

  • GetFirstRuntimeFeatureIdBlueprint

    The first feature id placed at runtime: feature ids below it were loaded with the save (or authored).

  • EvaluateFeature

    What a feature would do, with nothing changed: the preview path.

  • CommitFeature

    Stage, validate and commit one feature (Id 0 = add, else replace in place) as one world transaction.

  • RemoveFeature

    Remove a feature; later features re-daylight against the ground beneath.

  • ApplyUndo

    Apply an undo or redo token.

  • CommitPlate

    Commit a plate (pad, yard, apron), stated in world cm, with no owner.

  • RemoveFeatureByIdBlueprint

    Remove a feature by id.

  • BeginStrokeBlueprint

    Start a stroke, ending an open one first (its EndStroke record and events go out before).

  • ApplyBrushBlueprint

    Apply one brush step, stated in world cm, under the sculpt limits.

  • ApplySplatBlueprint

    Apply one splat dab: one masked Paint step for each used channel of the splat, in the order red, green, blue, alpha, inside the open stroke, so the whole stroke is one undo however many dabs it holds.

  • EndStrokeBlueprint

    Finish the open stroke: its before-image joins the bounded ring; broadcasts its record, OnStrokeEndedBP and OnSculptStroke.

  • GetLastSculptRefusalBlueprint

    Why the authority's last Refused brush step was refused, in words (a limit, an unknown mask, a stamp over the limits); empty when it has refused nothing.

  • RegisterBrushBlueprint

    Register a brush asset's baked mask with this terrain, so brushes naming its id apply.

  • RegisterBrushSetBlueprint

    Register every baked brush of a set.

  • RegisterSplatBlueprint

    Register a splat asset's baked channel masks with this terrain, and return the splat to paint with.

  • RegisterBrushMaskFromPixelsBlueprint

    Register raw single-channel pixels as a mask, baked with the asset-free defaults of the usage (256 x 256 at 8 bits for a strength mask, 1024 x 1024 at 16 for a height mask).

  • RegisterBrushMask

    Register an already made mask (C++: FBrushMask::Decode, OrbdaleTerrain::BrushBake).

  • UnregisterBrushMaskBlueprint

    Stop holding a mask.

  • IsBrushMaskKnownBlueprint

    Whether this terrain holds the mask, so a brush naming it applies.

  • GetBrushMaskInfoBlueprint

    What the registry says about a mask.

  • UndoStrokeBlueprint

    Undo the most recent stroke still in the ring, ending an open stroke first.

  • RedoStrokeBlueprint

    Put back the stroke the last UndoStroke took back.

  • GetSculptStateBlueprint

    The sculpt tool's state: open stroke, undo and redo depth, ring bytes, replica queue.

  • GetSculptLimitsBlueprint

    The limits this terrain enforces, cm (its settings when it was created); the defaults without a terrain.

  • ApplySculptRecordBlueprint

    Apply one encoded sculpt record (a command or an undo/redo patch) received from the game's replication.

  • ApplySculptCommand

    C++ form of ApplySculptRecord for a decoded command.

  • ApplySculptPatch

    C++ form of ApplySculptRecord for a decoded undo or redo patch.

  • IsSculptReplica

    Whether this world applies sculpt records as a replica.

  • SetSculptReplica

    Override the sculpt role: for a game whose replication does not follow the net mode, and for tests.

  • IsReplica

    Whether this world applies the authority's records, every edit kind, as a replica: by default a client world (NM_Client).

  • SetReplica

    Override the role (a game whose replication does not follow the net mode; tests).

  • AddRecordListener

    Listen to the authority's one ordered record stream, in C++ (the net hub does).

  • RemoveRecordListener

    Stop a listener AddRecordListener added.

  • GetNextRecordSeqBlueprint

    The position the authority's next record gets: 1 before the first.

  • AppendTerrainCheckpointBlueprint

    Append a Checkpoint record to the stream: SyncHash, the sculpt digest and the next feature id here and now.

  • ApplyTerrainRecordBlueprint

    Apply one of the authority's records on a replica, in Seq order: every kind in one order (sculpt and stack ops share it, since the keep-out guard reads the stack).

  • ApplyTerrainRecordView

    C++ form of ApplyTerrainRecord for a decoded record (Command filled for Sculpt).

  • LoadReplicaSnapshotBlueprint

    A replica's join: load the authority's save bytes, taken when its next record was Seq + 1, and apply its records from Seq + 1 on.

  • GetSyncHash

    FTerrainWorld::SyncHash: what a checkpoint and a join compare; 0 without a terrain.

  • GetRecordReplica

    The replica's record queue and checkpoint verdicts; null before the first record or snapshot, and on the authority.

  • ApplySculptRequest

    Apply a client's sculpt request on the authority, as that author's: each author has one open stroke of its own, and a request names the client's stroke id, which the authority binds to the stroke it opens.

  • SculptStepGroundFits

    Whether a brush step of Author's stroke keeps that stroke within a limit on the ground it keeps resident.

  • GetBakeWaitBlueprint

    Why ground near a plate or corridor is not baked yet, at a place.

  • ApplySculptRequestBytesBlueprint

    Blueprint form of ApplySculptRequest: a sculpt command, or an undo or redo patch (its tiles are ignored), as the sculpt component's OnCommandRequested bytes.

  • ApplyUndoRequest

    Take back (or put back) the author's newest stroke, ending its open stroke first: refused as Conflict when another stroke wrote its tiles since.

  • EndRequestStroke

    End the author's open stroke, as its EndStroke request would: a link that left or joins again.

  • GetOpenStrokeCount

    Open strokes on the authority, every author's.

  • GetSculptDigest

    The sculpt command digest so far (FSculptReplayer::Digest): a checkpoint's and a join's SculptDigest.

  • RegisterInvokerBlueprint

    Keep full-resolution ground resident around an actor (a construction cursor, a vehicle).

  • UnregisterInvokerBlueprint
  • GetStreamingStats

    The streamer's counters and queue depths, for debug overlays, scenarios and tests.

  • IsStreamingIdle

    True when no tile load is in flight, no queued request is launchable (parked stale requests do not count), and the far data has no work left: no ring tile held back and no far-overlay job waiting or out (FTerrainStreamer::IsIdle).

  • SetTileLoadsHeldForTests

    Tests: hold every tile load, so no tile lands until released, or release them.

  • HasPendingChunkWork

    True while the chunk manager has work left: a chunk dirty, a posts build in flight, or residency not re-read since its last change (FTerrainChunkManager::HasPendingWork).

  • GetRvtStatusBlueprint

    What the terrain's colour RVT is doing, as the renderer last reported it (FOrbdaleTerrainRvtStatus).

  • IsRvtIdleBlueprint

    True when the colour RVT has no reason left to produce pages: no edit waiting to invalidate, no settle and no upload boost running (FOrbdaleTerrainRvtStatus).

  • IsGrassIdleBlueprint

    True when no grass build is pending: the grass has no unbuilt sub-cell, task or waiting result, and no chunk's posts wait for its next tick (FTerrainGrassSystem::IsIdle, as the renderer last reported it).

  • SetGrassIdle

    The renderer's report behind IsGrassIdle.

  • SetRvtStatus

    The renderer's report behind GetRvtStatus, once per tick and when its RVT ends.

  • GetInvokers

    The registered invokers.

  • SaveTerrainToBytesBlueprint

    The terrain's mutable state as versioned bytes: feature stack, sculpt layer and the natural ground's identity, never baked tiles.

  • LoadTerrainFromBytesBlueprint

    Replace the stack and sculpt layer from bytes, re-bake, publish once.

  • GetStateHashBlueprint

    Identity of the mutable state (desync checks, save round trips).

  • SaveTerrainToBytesWithOptionsBlueprint

    SaveTerrainToBytes keeping only some owners' features (the editor's authoring layer).

  • SaveTerrainToFile

    Write the terrain's save file: a snapshot pinned now (the world may go on changing), streamed on a task into <Path>.tmp, flushed and renamed over Path.

  • FlushTerrainFileSave

    Wait for the save file in flight, if any, and fire its Done.

  • IsTerrainFileSaveInFlight

    A save file is being written.

  • LoadTerrainFromFile

    Load a save file.

  • IsTerrainFileInUse

    Some sculpted tile still pages from the save file at Path: it must not be deleted or overwritten.

  • LoadTerrainFromArchive

    Load a version-4 save streamed from an archive (an editor bulk-data payload): every byte read and checked, every code kept in RAM.

  • SaveTerrainToArchive

    Stream a save into an archive (an editor bulk-data payload).

  • GetSculptPagingStats

    The pager's and the world's paging counters; zero without a terrain.

  • SaveTerrainAsync

    Save the terrain beside a game's save slot, streamed on a task: the file is Slot.N.suffix in GetSaveDirectory, where N is one more than the highest existing N of the slot, so a world that pages from the previous save never has its file written over.

  • LoadTerrainAsync

    Load the save a reference names, through LoadTerrainFromFile with the reference's file hash: a file that is not the save the game recorded is refused as Corrupt.

  • GetSaveDirectorystatic

    The folder terrain saves go in: <Project>/Saved/SaveGames, where a USaveGame slot lives on desktop.

  • IsValidSaveSlotNamestatic

    Whether a slot name is acceptable: 1 to 100 characters, none of the path and file-name characters (slash, backslash, colon, star, question mark, quote, angle brackets, bar), no control character, not ...

  • ResolveSavePathstatic

    The absolute path a reference names, or an empty string when the reference is not valid or its file name tries to leave GetSaveDirectory.

Properties

NameTypeDefaultMeaning
kMaxGroundHoldsint3216

Ground holds kept at most (CommitFeature); a new one beyond releases the least recently refused.

kGroundHoldTimeout_sdouble60.0

Wall-clock seconds a ground hold lasts without a retry of its key (CommitFeature).

OnTerrainRecordBPBlueprintAssignableFOnOrbdaleTerrainRecordBP—

Every record the authority applied, in its one order, with its position and author.

Never on a replica.

OnGroundChangedBPBlueprintAssignableFOnOrbdaleTerrainGroundChangedBP—

Blueprint form of OnGroundChanged.

Bounds span the changed edit tiles in plan and ±100 km in Z.

OnGroundChangedFOnTerrainGroundChanged—

Native form of OnGroundChangedBP: renderer, navigation and gameplay listeners.

Mass polls GetRevision instead.

OnTerrainCreatedFOnTerrainLifecycle—

After CreateTerrain succeeded, with the host.

Game thread.

OnTerrainWillBeDestroyedFOnTerrainLifecycle—

First thing in DestroyTerrain, with the host, while the world, the chunks and the provider are still there: the last moment to read the ground (the editor captures its authoring layer here).

Edits from a listener are refused.

OnTerrainDestroyedFOnTerrainLifecycle—

After DestroyTerrain finished (HasTerrain is false), with the former host.

Too late to read anything.

OnTerrainCreatedBPBlueprintAssignableFOnOrbdaleTerrainLifecycleBP—

Blueprint form of OnTerrainCreated.

OnTerrainWillBeDestroyedBPBlueprintAssignableFOnOrbdaleTerrainLifecycleBP—

Blueprint form of OnTerrainWillBeDestroyed.

OnTerrainDestroyedBPBlueprintAssignableFOnOrbdaleTerrainLifecycleBP—

Blueprint form of OnTerrainDestroyed.

OnChunkPostsReadyFOnTerrainChunkPostsReady—

A chunk's heights are ready or changed: the renderer builds or updates its render chunk.

OnChunkEvictedFOnTerrainChunkEvicted—

A chunk left the residency set.

OnChunkHeightsLiveFOnTerrainChunkPostsReady—

During a stroke: a chunk's posts changed this frame (heights, or a painted channel), read once on a task, with no collision attached.

Game thread. At most once per frame per chunk, one frame after the publish at the latest; never for a commit, undo, load or stream; no read happens while nothing is bound; the renderer updates its height texture in place and re-creates nothing. OnChunkPostsReady stays the throttled signal (collision and posts agree; re-create the proxy). Keep the newest Posts->Revision per chunk.

OnSculptStrokeFOnTerrainSculptStroke—

A stroke opened (empty bounds) or closed (the edit tiles its publishes touched).

Game thread, on the authority and on a replica (when the tick applies the authority's Begin and End). A load closes an open stroke without a record. Edits from a listener are refused.

OnSculptRecordBPBlueprintAssignableFOnOrbdaleTerrainSculptRecordBP—

Every sculpt record the authority applied, as bytes for replication, in order: BeginStroke, one Brush per applied step, EndStroke (before an undo patch, when the undo ended the stroke), UndoPatch and RedoPatch.

Never on a replica. Edits from a listener are refused.

OnStrokeEndedBPBlueprintAssignableFOnOrbdaleTerrainStrokeEndedBP—

A stroke ended, with what it moved in this world (FTerrainWorld::LastStrokeVolumes).

Price a stroke on the authority's: a replica's feature volumes leave out tiles it had not loaded.

Blueprint