class

TerrainSystem

Module
Game
Header
#include "Terrain/TerrainSystem.h"
Namespace
Mowo

Constructors

SignatureNameDescription
TerrainSystem() = defaultTerrainSystem
~TerrainSystem() override = default~TerrainSystem
TerrainSystem(const TerrainSystem&) = deleteTerrainSystem

Public functions

ReturnsNameDescription
TerrainSystem&operator=
voidInitialize
voidShutdown
voidUpdate
boolGetWeightmapPixelsWeightmap paint API (editor brushes call these; R/G/B/A = layer 0-3 weights).
voidResolveSurfacesFromWeightmapCollapses an RGBA8 layer weightmap into one surface per collision square, taking the heaviest of the four layers at each square's centre.
voidResolveSurfacesFromWeightmap8
boolSetWeightmapPixels
boolUploadWeightmapRegion
Ref<Texture2D>GetWeightmapTexture
boolEnsureWeightmap2
uint8_t*GetWeightmap2PixelData
boolGetWeightmap2Pixels
boolSaveWeightmap2ToFile
voidMarkWeightRegionDirty
boolEnsureWeightmapCreates a paintable weightmap when the component references none, seeded from the procedural slope/height rules so the first stroke blends into what is already on screen instead of snapping the whole terrain to one layer.
uint8_t*GetWeightmapPixelDataMutable view of the CPU weightmap the GPU texture mirrors — the paint brush writes here and follows with UploadWeightmapRegion over the same rect.
FEditableHeightfield*EnsureEditableHeightsSculpt session The editable float grid backing height edits.
boolSetEditableHeightsInstalls a field wholesale — a tiled import cutting one oversized source into a grid, or a generator.
const FEditableHeightfield*FindEditableHeights
boolHasEditableHeights
voidDiscardEditableHeights
uint32_tAdoptUnsavedEditsTakes the live edit state of a world this one was copied from — sculpted heights, painted weightmaps, retopo offsets — for every entity that exists here too (a play-in-editor copy keeps the source's entity IDs).
uint32_tRebuildHeightRegionRebuilds only the chunks whose texel footprint intersects region (an empty region rebuilds every chunk).
voidRefreshCollisionResamples the Jolt heightfield from the edited grid.
boolSaveHeightsToFilePersistence Heights write as headerless little-endian 16-bit (the .r16 the decoder already reads back at full precision), normalized against heightScale.
boolSaveWeightmapToFile
floatGetEditedHeightRangeLargest edited height, for choosing a heightScale that does not clip the sculpt on save.
voidAcceptFingerprintMarks the component's current field values as already built, so writing freshly saved heightmap/weightmap paths back into it does not trigger a full rebuild of geometry that is already correct.
FTerrainOpResultApplySculptStampThe seam a viewport tool calls.
FTerrainOpResultApplyPaintStampPaints one layer (negative = erase toward a hole) and pushes the dirty rect to the GPU weightmap, which is what invalidates the RVT pages.
FTerrainOpResultApplyRampOp
voidEndStroke
FTerrainOpResultApplyHydraulicErosionOffline whole-field passes.
FTerrainOpResultApplyThermalErosion
FTerrainOpResultStepHydraulicErosionThe same passes a slice at a time, for the editor to spread over frames.
FTerrainOpResultStepThermalErosion
FTerrainOpResultGenerateFromNoise
FTerrainOpResultApplySplinesGrades the component's spline corridor into the heightfield and, when spline_layer is set, paints that layer along it.
FTerrainEditLayerStack*EnsureEditLayersEdit layers.
FTerrainEditLayerStack*FindEditLayers
uint32_tRecompositeLayers
boolSaveEditLayersEdit-layer persistence.
boolLoadEditLayers
uint32_tFlushEditsForSceneWrites every dirty edit-layer stack and retopo offset grid beside the scene file and points each component at what it wrote, so a plain "save the level" keeps the terrain non-destructive without the artist remembering to press Save Stack.
FTerrainOffsetField*EnsureOffsetsRetopologize.
const FTerrainOffsetField*FindOffsets
boolHasOffsets
voidClearOffsets
FTerrainOpResultApplyRetopologize
FTerrainOpResultApplyRetopoStamp
boolSaveOffsets
boolLoadOffsets
boolBuildOffsetPacket
floatDecodeOffsetHalf
uint32_tUploadOffsetRegionPushes the offset grid to the GPU for the touched rect, creating the texture on first use.
Ref<Texture2D>GetOffsetTexture
boolBuildNavGeometryHole-aware navigation geometry: a triangle soup in ENTITY-LOCAL meters at resolution samples per side, with every square whose weightmap texel sums to nothing left out.
uint32_tTickTileStreamingTile streaming.
voidCollectStreamingTilesThe tiles this world holds, in the shape the pure decision function takes.
boolImportHeightmapImport / export
boolExportHeights
boolExportWeightmapLayer
boolImportWeightmapLayer
boolHasCdlodRenderData
Ref<Texture2D>GetHeightTexture
uint32_tStitchAdjacentTiles

Function details

TerrainSystem

C++
TerrainSystem() = default

~TerrainSystem

C++
~TerrainSystem() override = default

TerrainSystem

C++
TerrainSystem(const TerrainSystem&) = delete

operator=

C++
TerrainSystem& operator=(const TerrainSystem&) = delete

Initialize

C++
void Initialize(World* world) override

Shutdown

C++
void Shutdown() override

Update

C++
void Update(float deltaTime) override

GetWeightmapPixels

C++
bool GetWeightmapPixels(EntityID entity, std::vector<uint8_t>& outPixels, uint32_t& outWidth, uint32_t& outHeight) const

Weightmap paint API (editor brushes call these; R/G/B/A = layer 0-3 weights). The CPU-side RGBA8 copy is authoritative; SetWeightmapPixels replaces it wholesale (recreates the GPU texture — the image is immutable-size), UploadWeightmapRegion pushes a dirty rect of the CPU copy to the existing GPU texture in place (the per-stroke hot path).

ResolveSurfacesFromWeightmap

C++
static void ResolveSurfacesFromWeightmap(const uint8_t* pixels, uint32_t width, uint32_t height, const ESurfaceType* layerSurfaces, uint32_t sampleCount, std::vector<ESurfaceType>& out)

Collapses an RGBA8 layer weightmap into one surface per collision square, taking the heaviest of the four layers at each square's centre. layerSurfaces is 4 entries, matching the weightmap's RGBA channels.

ResolveSurfacesFromWeightmap8

C++
static void ResolveSurfacesFromWeightmap8(const uint8_t* pixelsA, const uint8_t* pixelsB, uint32_t width, uint32_t height, const ESurfaceType* layerSurfaces, uint32_t sampleCount, std::vector<ESurfaceType>& out)

SetWeightmapPixels

C++
bool SetWeightmapPixels(EntityID entity, const uint8_t* rgba8, uint32_t width, uint32_t height)

UploadWeightmapRegion

C++
bool UploadWeightmapRegion(EntityID entity, uint32_t x, uint32_t y, uint32_t width, uint32_t height, const uint8_t* rgba8 = nullptr)

GetWeightmapTexture

C++
Ref<Texture2D> GetWeightmapTexture(EntityID entity) const

EnsureWeightmap2

C++
bool EnsureWeightmap2(EntityID entity)

GetWeightmap2PixelData

C++
uint8_t* GetWeightmap2PixelData(EntityID entity, uint32_t& outWidth, uint32_t& outHeight)

GetWeightmap2Pixels

C++
bool GetWeightmap2Pixels(EntityID entity, std::vector<uint8_t>& outPixels, uint32_t& outWidth, uint32_t& outHeight) const

SaveWeightmap2ToFile

C++
bool SaveWeightmap2ToFile(EntityID entity, const std::string& absPath) const

MarkWeightRegionDirty

C++
void MarkWeightRegionDirty(EntityID entity, uint32_t x0, uint32_t y0, uint32_t x1, uint32_t y1)

EnsureWeightmap

C++
bool EnsureWeightmap(EntityID entity, uint32_t resolution = 0)

Creates a paintable weightmap when the component references none, seeded from the procedural slope/height rules so the first stroke blends into what is already on screen instead of snapping the whole terrain to one layer. Idempotent; returns false when the terrain has no splat material.

GetWeightmapPixelData

C++
uint8_t* GetWeightmapPixelData(EntityID entity, uint32_t& outWidth, uint32_t& outHeight)

Mutable view of the CPU weightmap the GPU texture mirrors — the paint brush writes here and follows with UploadWeightmapRegion over the same rect. Null when the entity has no weightmap.

EnsureEditableHeights

C++
FEditableHeightfield* EnsureEditableHeights(EntityID entity)

Sculpt session The editable float grid backing height edits. Built lazily from the component's heightmap at whatever precision the source carries, or flat when it references none. Once present it becomes the authority: a fingerprint rebuild composes the mesh from it, not from the file.

SetEditableHeights

C++
bool SetEditableHeights(EntityID entity, const FEditableHeightfield& field)

Installs a field wholesale — a tiled import cutting one oversized source into a grid, or a generator. The layer stack is dropped with it: deltas authored against the old grid cannot be recomposited onto a new one, and keeping them would shift every stroke by a row. Clears the component's fingerprint so the next Update rebuilds mesh, collision and CDLOD data at whatever resolution the new field carries.

FindEditableHeights

C++
const FEditableHeightfield* FindEditableHeights(EntityID entity) const

HasEditableHeights

C++
bool HasEditableHeights(EntityID entity) const

DiscardEditableHeights

C++
void DiscardEditableHeights(EntityID entity)

AdoptUnsavedEdits

C++
uint32_t AdoptUnsavedEdits(const TerrainSystem& source)

Takes the live edit state of a world this one was copied from — sculpted heights, painted weightmaps, retopo offsets — for every entity that exists here too (a play-in-editor copy keeps the source's entity IDs). A sculpt lives here and not in the scene document until the level is saved, so without it a copy rebuilt every terrain from the files on disk and PIE played on the last saved landscape. Call before the copy's first Update so its first build composes from the adopted field. Returns how many terrains took edited heights.

RebuildHeightRegion

C++
uint32_t RebuildHeightRegion(EntityID entity, const FTerrainTexelRegion& region)

Rebuilds only the chunks whose texel footprint intersects region (an empty region rebuilds every chunk). Returns how many chunks were rebuilt — the measurement the brush stroke cost is dominated by.

RefreshCollision

C++
void RefreshCollision(EntityID entity)

Resamples the Jolt heightfield from the edited grid. Separate from the mesh rebuild because it invalidates the physics body; call it once at stroke end, not per dab.

SaveHeightsToFile

C++
bool SaveHeightsToFile(EntityID entity, const std::string& absPath, float heightScale) const

Persistence Heights write as headerless little-endian 16-bit (the .r16 the decoder already reads back at full precision), normalized against heightScale. The weightmap writes as an RGBA8 PNG. Both take an absolute path; the caller sets the component's VFS path to match.

SaveWeightmapToFile

C++
bool SaveWeightmapToFile(EntityID entity, const std::string& absPath) const

GetEditedHeightRange

C++
float GetEditedHeightRange(EntityID entity) const

Largest edited height, for choosing a heightScale that does not clip the sculpt on save. Returns 0 when the entity has no edit session.

AcceptFingerprint

C++
void AcceptFingerprint(EntityID entity)

Marks the component's current field values as already built, so writing freshly saved heightmap/weightmap paths back into it does not trigger a full rebuild of geometry that is already correct.

ApplySculptStamp

C++
FTerrainOpResult ApplySculptStamp(EntityID entity, const FTerrainBrushStamp& stamp)

The seam a viewport tool calls. The stamp's world XZ is TERRAIN-LOCAL meters (origin at the terrain centre); worldSize on the stamp's brush is overwritten from the component, so a tool never has to know it. The op routes through the active edit layer, then refreshes the CDLOD height texture and quadtree bounds for the touched rect only. Collision is NOT refreshed — that costs a physics-body rebuild, so call EndStroke once when the drag releases.

ApplyPaintStamp

C++
FTerrainOpResult ApplyPaintStamp(EntityID entity, const FTerrainBrushStamp& stamp, int32_t layer)

Paints one layer (negative = erase toward a hole) and pushes the dirty rect to the GPU weightmap, which is what invalidates the RVT pages.

ApplyRampOp

C++
FTerrainOpResult ApplyRampOp(EntityID entity, const FTerrainRampParams& ramp)

EndStroke

C++
void EndStroke(EntityID entity)

ApplyHydraulicErosion

C++
FTerrainOpResult ApplyHydraulicErosion(EntityID entity, const FTerrainHydraulicParams& params)

Offline whole-field passes. Each is one explicit command, not a dab: they rewrite the field, rebuild every chunk and refit collision once.

ApplyThermalErosion

C++
FTerrainOpResult ApplyThermalErosion(EntityID entity, const FTerrainThermalParams& params)

StepHydraulicErosion

C++
FTerrainOpResult StepHydraulicErosion(EntityID entity, const FTerrainHydraulicParams& params, FTerrainErosionRun& run, int32_t budget)

The same passes a slice at a time, for the editor to spread over frames. Every slice redraws the chunks; collision is refit once, by the slice that finishes the run, because refitting it every frame of a long pass would cost more than the pass.

StepThermalErosion

C++
FTerrainOpResult StepThermalErosion(EntityID entity, const FTerrainThermalParams& params, FTerrainErosionRun& run, int32_t budget)

GenerateFromNoise

C++
FTerrainOpResult GenerateFromNoise(EntityID entity, const std::vector<FTerrainNoiseLayer>& stack, float baseHeight)

ApplySplines

C++
FTerrainOpResult ApplySplines(EntityID entity)

Grades the component's spline corridor into the heightfield and, when spline_layer is set, paints that layer along it.

EnsureEditLayers

C++
FTerrainEditLayerStack* EnsureEditLayers(EntityID entity)

Edit layers. Created lazily around the current editable field; the field stays the composite everything downstream reads.

FindEditLayers

C++
FTerrainEditLayerStack* FindEditLayers(EntityID entity)

RecompositeLayers

C++
uint32_t RecompositeLayers(EntityID entity)

SaveEditLayers

C++
bool SaveEditLayers(EntityID entity, const std::string& absPath)

Edit-layer persistence. Save writes base + every delta plane to an absolute path; the caller then points the component's edit_layers_path at the matching VFS path so the scene records it. Load replaces the live stack and recomposites, so the field the renderer and the collider read still equals base + visible layers. EnsureEditLayers loads the component's path once per path change, which is what makes a reopened scene non-destructive again without an explicit editor action.

LoadEditLayers

C++
bool LoadEditLayers(EntityID entity, const std::string& vfsPath)

FlushEditsForScene

C++
uint32_t FlushEditsForScene(const std::string& scenePath)

Writes every dirty edit-layer stack and retopo offset grid beside the scene file and points each component at what it wrote, so a plain "save the level" keeps the terrain non-destructive without the artist remembering to press Save Stack. scenePath is the VFS path the scene itself is written to; the blobs land next to it as "<scene stem>_Terrain<entity>.mtel" / ".mtro". Returns how many files were written. The manual Save / Reload buttons stay: an explicit save is still what you want after an experiment you do NOT intend to keep.

EnsureOffsets

C++
FTerrainOffsetField* EnsureOffsets(EntityID entity)

Retopologize. The heightfield is never rewritten — the offset grid says where each of its samples SITS, so the surface is unchanged and only the tessellation slides along it.

FindOffsets

C++
const FTerrainOffsetField* FindOffsets(EntityID entity) const

HasOffsets

C++
bool HasOffsets(EntityID entity) const

ClearOffsets

C++
void ClearOffsets(EntityID entity)

ApplyRetopologize

C++
FTerrainOpResult ApplyRetopologize(EntityID entity, const FTerrainRetopoParams& params)

ApplyRetopoStamp

C++
FTerrainOpResult ApplyRetopoStamp(EntityID entity, const FTerrainBrushStamp& stamp, const FTerrainRetopoParams& params)

SaveOffsets

C++
bool SaveOffsets(EntityID entity, const std::string& absPath) const

LoadOffsets

C++
bool LoadOffsets(EntityID entity, const std::string& vfsPath)

BuildOffsetPacket

C++
static bool BuildOffsetPacket(const FTerrainOffsetField& offsets, const FTerrainTexelRegion& region, FTerrainOffsetPacket& out)

DecodeOffsetHalf

C++
static float DecodeOffsetHalf(uint16_t encoded)

UploadOffsetRegion

C++
uint32_t UploadOffsetRegion(EntityID entity, const FTerrainTexelRegion& region)

Pushes the offset grid to the GPU for the touched rect, creating the texture on first use. Called from the retopo ops themselves — the same produce-phase seam the weightmap upload uses, because recording GPU work from a World update would land it in the wrong command buffer.

GetOffsetTexture

C++
Ref<Texture2D> GetOffsetTexture(EntityID entity) const

BuildNavGeometry

C++
bool BuildNavGeometry(EntityID entity, uint32_t resolution, std::vector<Vec3>& outVertices, std::vector<int32_t>& outIndices) const

Hole-aware navigation geometry: a triangle soup in ENTITY-LOCAL meters at resolution samples per side, with every square whose weightmap texel sums to nothing left out. The nav bake walks MeshRenderers for its snapshot and the CDLOD terrain contributes no CPU mesh, so terrain is absent from the navmesh entirely; this is the source that closes it, and it skips holes by construction rather than by a post-pass.

TickTileStreaming

C++
uint32_t TickTileStreaming(const Vec3& cameraPos, const StreamingSettings& settings)

Tile streaming. Tiles spawned by the tiled importer carry streaming_tile; this classifies them against the camera using the same three radii the sector streamer uses and builds or releases the ones whose residency changed, at most settings.maxConcurrentLoads per call. Returns how many tiles changed state.

CollectStreamingTiles

C++
void CollectStreamingTiles(std::vector<FTerrainTileDesc>& out) const

The tiles this world holds, in the shape the pure decision function takes. Exposed so a caller can plan without applying.

ImportHeightmap

C++
bool ImportHeightmap(EntityID entity, const std::string& path, float heightScale)

Import / export

ExportHeights

C++
bool ExportHeights(EntityID entity, const std::string& absPath, float heightScale, bool png16) const

ExportWeightmapLayer

C++
bool ExportWeightmapLayer(EntityID entity, int32_t layer, const std::string& absPath) const

ImportWeightmapLayer

C++
bool ImportWeightmapLayer(EntityID entity, int32_t layer, const std::string& absPath)

HasCdlodRenderData

C++
bool HasCdlodRenderData(EntityID entity) const

GetHeightTexture

C++
Ref<Texture2D> GetHeightTexture(EntityID entity) const

StitchAdjacentTiles

C++
uint32_t StitchAdjacentTiles()
Generated from Terrain/TerrainSystem.h via game.json · Nov 5, 2026Version 1.0.0