GeoForgeRuntime DOC

GeoForgeRuntime - Block-Based Cubic World

GeoForgeRuntime is a runtime Unreal Engine plugin for building streamed block-based worlds with legacy and advanced terrain generation, block-aware gameplay edits, reusable voxel structures, profile-driven biomes, data-driven feature spawning, voxel-graph generation layers, runtime targeting previews, multiplayer-safe terrain edits, optional water overlays, and multiple terrain render paths. The included editor module adds custom asset editors, terrain diagnostics, viewport sculpting tools, and authoring workflows across the GeoForge asset ecosystem.

Supported version

  • Unreal Engine 5.7.x
  • Target platform: Win64

Required plugin

  • ProceduralMeshComponent must stay enabled because GeoForgeRuntime depends on it.

Main plugin pieces

  • GeoForgeInfiniteTerrainActor is the main runtime actor that generates, streams, renders, and edits the terrain world.
  • GeoForgeTerrainBlueprintLibrary exposes Blueprint utility nodes for digging, placement, block-aware editing, runtime targeting, terrain queries, generation overrides, structure stamping, and save/load.
  • GeoForgeTerrainSaveGame is the SaveGame type used by the quick-save Blueprint helpers.
  • GeoForgeAdvancedTerrainProfile is a reusable data asset for the advanced terrain pipeline, Earth-style domain shaping, hydrology, preview tuning, and depth-policy related defaults.
  • GeoForgeBiomeProfile is a reusable data asset for biome masks, preview colors, macro layout, and effective biome material behavior.
  • GeoForgeBlockDefinition is a reusable data asset for named block types, block-aware placement, optional mesh visuals, digging/drop overrides, and surface-scatter rules.
  • GeoForgeBlockRegistry is a reusable data asset that stores a shared logical block catalog for multiple terrain actors or terrain block profiles.
  • GeoForgeTerrainBlockProfile is a reusable data asset that layers shared registries, profile-local block definitions, weighted tagged block pools, terrain block selection rules, and generated-material fallback mappings onto natural terrain generation.
  • GeoForgeFeatureProfile is a reusable data asset for staged, data-driven generation of actors, structures, and ore-like block clusters.
  • GeoForgeVoxelGraph is a lightweight voxel-graph-style generation asset for ordered fill/carve rules applied before chunk geometry is built.
  • GeoForgeVoxelStructure is a reusable data asset for authoring relative voxel edits that can be stamped or live-modified into terrain.
  • GeoForgeVoxelStructureStampActor is an editor helper actor for previewing and applying structure stamps onto a target terrain actor.
  • GeoForgeVoxelStructureModifierActor is a live structure modifier actor that affects chunk generation non-destructively instead of baking a one-time authored stamp.
  • GeoForgeTerrainSelectionPreviewActor is the gameplay-facing hover outline, placement ghost, and sphere-edit preview actor for crosshair or actor-view targeting.
  • GeoForgePhaseStateControllerComponent is a gameplay component that queries terrain overlap and can locally fade terrain, water, and clouds around an actor.

Editor module tools

  • GeoForge Terrain editor mode adds viewport authoring tools for Place Voxel, Remove Voxel, Flatten, Raise Terrain, Lower Terrain, Smooth Terrain, and Stamp Structure.
  • The terrain mode exposes brush radius, sculpt strength, sculpt falloff, material override, surface offset, block-definition-aware painting, active structure selection, and structure rotation controls.
  • GeoForge Advanced Terrain Profile Editor adds a dedicated preview workflow for advanced height, hydrology, coastline, domain, and cross-section style authoring.
  • GeoForge Biome Profile Editor now supports multiple diagnostic preview modes, including Combined, Biome Mask, Height Style, Coastline Moisture, Climate Mask, Temperature Frost, Moisture Forest, Wetness Rivers, Surface Material, and Transition Mask.
  • GeoForge Voxel Structure Editor adds a preview viewport, add/remove brush tools, block-aware authoring, static-mesh conversion, and heightmap-to-structure import.
  • The editor module customizes GeoForgeInfiniteTerrainActor details and includes an in-editor help workflow for common setup, rendering, networking, and authoring tasks.
  • The editor module registers a GeoForge asset category and Content Browser factories/actions for creating GeoForgeBiomeProfile, GeoForgeAdvancedTerrainProfile, GeoForgeBlockDefinition, GeoForgeFeatureProfile, and GeoForgeVoxelStructure assets.
  • The editor module also includes a GeoForge Structure Stamp actor factory for spawning a ready-to-preview stamp actor from a GeoForge voxel structure asset.

First setup

  • Create or open a level.
  • Place GeoForgeInfiniteTerrainActor in the level.
  • Choose the overall world style with World Preset, then decide whether you want Legacy generation or the newer Advanced terrain pipeline through Generation Mode.
  • Adjust core terrain values such as Cell Size, Chunk Size In Cells, Chunk Height In Cells, World Seed, and your vertical or finite-world bounds settings.
  • If you use the advanced pipeline, create or assign a GeoForgeAdvancedTerrainProfile.
  • If you want profile-driven biome regions, create or assign a GeoForgeBiomeProfile, enable Use Biome Regions, and tune the biome asset.
  • If you want named gameplay blocks, add one or more GeoForgeBlockDefinition assets directly in Block Definitions, assign a shared GeoForgeBlockRegistry, or combine both workflows.
  • If you want scalable natural-terrain block resolution, assign a GeoForgeTerrainBlockProfile and configure its supplemental block definitions, weighted block pools, terrain block rules, and optional generated-material fallback mappings.
  • If you want additional generation layers, assign a GeoForgeFeatureProfile and/or a GeoForgeVoxelGraph.
  • Assign your terrain materials if you want custom visuals for surface, soil, rock, deep rock, water, sand, or snow. Enable Use General Biome Terrain Material if one shared terrain shader should handle multiple layers.
  • Choose the render path you want with Chunk Render Mode: classic procedural voxel terrain, instanced visible cubes, or a smooth marching-cubes surface.
  • If you want a continuous top water surface, enable Enable Water Surface Overlay.
  • If you want decorative systems, enable built-in cube trees, enable clouds, and choose the built-in cube-cloud visual style if you want blocky clouds.
  • Press Play. The terrain streams around the player by default, or around the actor assigned as the streaming source.

Main runtime actor

  • GeoForgeInfiniteTerrainActor is the main actor used to generate, stream, and control the terrain world.
  • If no streaming source actor is assigned, the plugin uses the player pawn at runtime. In editor preview workflows, it can also follow the active perspective viewport camera when editor auto rebuild is enabled.
  • The actor can stream around multiple player pawns in multiplayer, optionally replicate gameplay terrain edits, and synchronously prime terrain support under a target location before teleports or load restores.

Useful terrain settings

  • World Preset controls the broad starting terrain style.
  • Generation Mode switches between the legacy generator and the newer advanced terrain pipeline.
  • Horizontal Bounds Mode lets the terrain stay endless or become a finite centered world.
  • Shape Terrain As Island adds an actor-level island falloff for finite or isolated landmasses.
  • World Depth Policy controls whether the world stays legacy-height, grows downward with a safety floor, or opens into deeper streamed space.
  • View Distance In Chunks and Vertical View Distance In Chunks control how much terrain remains loaded around the streaming source.
  • Predictive Chunk Streaming and view-frustum chunk prioritization improve the order in which streaming work is processed.
  • Chunk Size In Cells, Chunk Height In Cells, and Cell Size control chunk scale and voxel scale.
  • World Seed keeps terrain generation deterministic.
  • Advanced Terrain Profile assigns the advanced terrain asset used by the newer domain-based generator.
  • Use Biome Regions, Biome Profile, and Biome Volume Overrides control profile-driven biome layout and local overrides.
  • Block Definitions, Block Registry, and Terrain Block Profile together build the effective logical block catalog used by block-aware gameplay nodes and generated-terrain block resolution.
  • Generated Material Block Mappings and terrain block profile fallback mappings translate natural material layers into logical block types for digging, drops, and gameplay-aware terrain queries.
  • Terrain Block Profile block pools and terrain block rules let generated cells resolve to logical blocks using weighted tagged pools filtered by biome, material layer, surface context, coast band, world height, and depth below surface.
  • Feature Profile and Voxel Graph add data-driven generation layers without requiring custom plugin code.
  • Persist Edited Cells Across Streaming keeps terrain edits when chunks unload and reload.
  • Replicate Terrain Edits enables server-authoritative gameplay terrain edits that replicate back to clients.
  • Chunk Render Mode switches between classic procedural terrain, instanced visible cubes, and marching-cubes smoothing.
  • Enable Water Surface Overlay builds a separate top water surface for rivers, lakes, and oceans.
  • Use General Biome Terrain Material routes non-water terrain through one shared biome-aware terrain material.
  • Use Async Chunk Generation and low-detail chunk placeholder settings help smooth chunk streaming cost.
  • Enable Built-In Cube Trees and Enable Clouds toggle optional decoration systems.

Shared block registry and terrain block profile workflow

  • GeoForgeBlockRegistry holds a shared reusable block catalog that multiple terrain actors or terrain block profiles can reference.
  • GeoForgeTerrainBlockProfile can reference a shared registry, add profile-local supplemental block definitions, provide profile-level generated-material fallback mappings, and define weighted tagged block pools plus terrain block selection rules.
  • The terrain actor builds an effective block catalog in this order: Terrain Block Profile Supplemental Block Definitions, then actor Block Definitions, then actor Block Registry, then the terrain block profile's referenced Block Registry. The first valid BlockTypeId wins when duplicates exist.
  • Actor-level Generated Material Block Mappings resolve first. Terrain block profile mappings only fill material layers that the actor does not already map locally.
  • Terrain block pools can auto-include matching registry blocks through semantic tags and can also add explicit weighted entries. Terrain block rules then pick from those pools using biome, material-layer, surface-context, coast-band, height, and depth filters.

Step-by-step use cases

Use case 1: Create a basic playable terrain world

  • Place GeoForgeInfiniteTerrainActor in the level.
  • Choose a preset such as Endless Seeded Terrain for a mixed world or Endless Flatlands for a simpler world.
  • Set your materials so the terrain has the look you want.
  • Increase View Distance In Chunks if you want terrain to remain visible farther away.
  • Press Play and move through the level to let terrain stream in.

Use case 2: Build a finite island or advanced-terrain world

  • Switch Generation Mode to the advanced pipeline.
  • Create or assign a GeoForgeAdvancedTerrainProfile.
  • If you want a fixed-size map, set Horizontal Bounds Mode to the finite centered option and tune the chunk extents.
  • If you want an island feel, enable Shape Terrain As Island and tune the radius and falloff values.
  • Use the advanced terrain profile editor to tune relief, domains, hydrology, and preview behavior.

Use case 3: Create exact one-block digging

  • From your player character, trace forward using Trace Terrain From Actor View or Trace Terrain Cell From Actor View.
  • If the trace hits GeoForge terrain, call Dig Terrain.
  • Pass the returned HitTerrainActor into the TerrainActor input.
  • Pass the returned HitLocation into the WorldLocation input.
  • Set bDigOnlyOneCube to true.
  • This setup is useful for mining, voxel editing, and precise terrain interaction.

Use case 4: Create radius digging or explosions

  • Trace terrain the same way with Trace Terrain From Actor View, or use any world impact location from your own gameplay system.
  • Call Dig Terrain with the terrain actor and impact location.
  • Set bDigOnlyOneCube to false.
  • Increase Radius to remove a larger area.
  • This setup is useful for explosions, terrain tools, weapons, or destruction abilities.

Use case 5: Place named blocks back into the world

  • Create one or more GeoForgeBlockDefinition assets for the logical block types you want gameplay to use.
  • Register them directly on the terrain actor, reuse them through a shared GeoForgeBlockRegistry, or assign a GeoForgeTerrainBlockProfile when you also want rule-driven natural terrain block resolution.
  • Use Get Registered Terrain Blocks if you want a block picker UI based on the terrain actor's effective block catalog.
  • Use Place Terrain Block, Place Terrain Block By Name, Add Terrain Block, or Add Terrain Block By Name when you want a specific block type rather than a generic filled voxel.
  • This is useful for builders, gameplay abilities, repair tools, and block-specific digging/drop behavior.

Use case 6: Quick Blueprint save and load

  • When the player saves the game, call Save Terrain To Slot.
  • Use a consistent SlotName such as TerrainSlot.
  • The quick-save helpers store their data in the plugin's GeoForgeTerrainSaveGame type inside a normal Unreal SaveGame slot.
  • When the player loads the game, call Load Terrain From Slot with the same slot name.
  • This is the fastest setup if you want save/load support entirely in Blueprints.

Use case 7: Use GeoForge with your own custom save system

  • Call Build Terrain Save Data when you want to capture the current terrain state.
  • Store the returned FGeoForgeTerrainSaveData inside your own SaveGame object or custom save structure.
  • Later, call Apply Terrain Save Data with that stored struct.
  • This setup is useful if you already have a larger custom save pipeline.

Use case 8: Build profile-driven biome regions

  • Create a GeoForgeBiomeProfile asset.
  • Open the GeoForge Biome Profile Editor and tune the biome masks, preview colors, macro layout, and diagnostic preview modes.
  • Assign the profile to your terrain actor and enable Use Biome Regions.
  • The preview workflow covers the same Region / Climate / Vegetation / Frost style signals used by runtime biome resolution, plus transition and surface-material focused diagnostics.

Use case 9: Add extra data-driven generation layers

  • Create a GeoForgeFeatureProfile asset when you want reusable feature rules for actors, structures, or ore-like block clusters.
  • Create a GeoForgeVoxelGraph asset when you want ordered fill/carve rules applied to every generated chunk before geometry is built.
  • Assign those assets on the terrain actor to extend generation without writing custom plugin code.

Use case 10: Author and reuse structures

  • Create a GeoForgeVoxelStructure asset and author its relative voxel edits.
  • Open the GeoForge Voxel Structure Editor if you want a dedicated preview viewport, add/remove brush tools, block-aware authoring, static-mesh voxelization, or heightmap import into the structure asset.
  • Stamp it with Apply Terrain Structure Asset Stamp or Apply Terrain Rotated Structure Asset Stamp from Blueprint.
  • In editor, you can also place a GeoForgeVoxelStructureStampActor, assign the structure asset, preview the stamp, and apply it directly to a terrain actor.
  • If you want a non-destructive live modifier instead of a one-time authored stamp, use GeoForgeVoxelStructureModifierActor.

Use case 11: Add gameplay-facing crosshair targeting and placement ghosts

  • Place a GeoForgeTerrainSelectionPreviewActor in the level or spawn one at runtime.
  • Let it auto-follow the first local player view, or assign a specific trace source actor.
  • Use the hover outline, placement ghost, and optional sphere-edit preview radius to show the player exactly what will be dug or placed.
  • Drive in-game UI with Get Hovered Runtime Target Details and Get Runtime Placement Target Details.

Use case 12: Enable multiplayer-safe terrain editing

  • Enable Replicate Terrain Edits when gameplay terrain edits should be server-authoritative.
  • Enable Stream Around All Player Pawns In Multiplayer if you need authority-side chunk support across multiple separated players.
  • Use the normal digging and placement Blueprint nodes; the terrain actor handles the replicated sparse edit state.

Use case 13: Use phase-state gameplay fades

  • Add a GeoForgePhaseStateControllerComponent to an actor that should query terrain overlap or phase through terrain-adjacent spaces.
  • Point it at a GeoForge terrain actor directly, or let it auto-resolve the nearest one.
  • Use its overlap queries and optional local fade volume to fade terrain, water, and clouds around the actor.

Use case 14: Use the GeoForge Terrain editor mode

  • Activate the GeoForge Terrain editor mode in Unreal Editor.
  • Choose Place Voxel, Remove Voxel, Flatten, Raise Terrain, Lower Terrain, Smooth Terrain, or Stamp Structure.
  • Set brush radius, sculpt strength, sculpt falloff, surface offset, and optional block definition settings for the current tool.
  • If you use Stamp Structure, assign the active structure asset and rotation step.
  • Click GeoForge terrain in the viewport to apply the edit. When placing voxels, holding the mouse button continues the add stroke for faster authoring.

Blueprint nodes and utility workflows

Generation override and structure nodes

  • Set Terrain Generation Voxel registers a single generation override at a world location.
  • Set Terrain Generation Block registers a block-aware generation override using a full block specification.
  • Set Terrain Generation Block By Name registers a block-aware generation override using a block type identifier from the terrain actor's effective block catalog.
  • Apply Terrain Structure Stamp applies an array of relative voxel edits at an origin.
  • Apply Terrain Structure Asset Stamp applies a reusable voxel structure asset.
  • Apply Terrain Rotated Structure Asset Stamp applies a voxel structure asset with a 90-degree yaw rotation index.
  • Clear Terrain Generation Overrides removes registered generation overrides and rebuilds the streamed world.

Terrain interaction and block nodes

  • Get Registered Terrain Blocks returns block IDs and display names from the terrain actor's effective block catalog.
  • Make Terrain Block Specification From Name builds a full placeable block specification from a block type identifier in the terrain actor's effective block catalog.
  • Dig Terrain removes one exact cube or a larger spherical area from the terrain.
  • Add Terrain adds one exact cube or a spherical area back into the terrain.
  • Add Terrain Block and Add Terrain Block By Name add named blocks instead of generic filled terrain.
  • Place Terrain Cube adds one exact cube to the nearest empty valid cell.
  • Place Terrain Block and Place Terrain Block By Name add one exact named block to the nearest empty valid cell.

Runtime targeting and terrain query nodes

  • Trace Terrain From Actor View traces forward from an actor view and returns whether GeoForge terrain was hit.
  • Trace Terrain Cell From Actor View resolves the hovered voxel and the snapped placement voxel for crosshair or actor-view targeting.
  • Build Terrain Trace Result builds snapped hover/placement voxel data from your own gameplay trace hit.
  • Query Exact Terrain Cell At World Location resolves the exact terrain cell under a world position.
  • Query Exact Terrain Cell By Global Cell resolves the exact terrain cell from integer global cell coordinates.
  • Query Terrain Column Diagnostics returns runtime biome, hydrology, visible fluid surface, and surface-material diagnostics for a terrain column.
  • Query Terrain Support Details Under Actor returns the terrain cells currently under an actor's feet and a primary support cell.
  • Query Terrain Cells Intersecting Actor Bounds returns the terrain cells intersecting the full actor bounds volume.

Save and load nodes

  • Build Terrain Save Data creates an FGeoForgeTerrainSaveData snapshot for your own save system.
  • Apply Terrain Save Data restores a previously built terrain snapshot.
  • Save Terrain To Slot quick-saves the terrain to a normal Unreal SaveGame slot.
  • Load Terrain From Slot quick-loads terrain from a SaveGame slot.
  • Delete Terrain Save Slot removes a quick-save slot.
  • Clear Terrain Saved State clears the currently stored saved terrain overrides on the active terrain actor.

Recommended node combinations

  • Trace Terrain Cell From Actor View + GeoForgeTerrainSelectionPreviewActor for gameplay crosshair targeting, hover outlines, and placement ghosts.
  • Trace Terrain From Actor View + Dig Terrain for mining and terrain interaction.
  • Make Terrain Block Specification From Name + Place Terrain Block for block-aware builders and voxel-style construction.
  • Set Terrain Generation Block By Name for persistent authored generation edits tied to a named gameplay block.
  • Apply Terrain Structure Asset Stamp + GeoForgeVoxelStructure for reusable authored terrain content.
  • Save Terrain To Slot + Load Terrain From Slot for fast Blueprint save/load support.
  • Build Terrain Save Data + Apply Terrain Save Data for custom save systems.

Biome, blocks, and generation layers

  • Biome profiles use Region, Climate, Vegetation, and Frost style channels plus macro layout tuning to resolve biome masks, terrain style, and effective surface-material behavior.
  • Block definitions, block registries, and terrain block profiles let gameplay work with named blocks while also driving natural terrain resolution through shared catalogs, weighted tagged pools, and filtered terrain block rules.
  • Generated material block mappings connect natural material-layer output to logical block types so digging, drops, and gameplay block queries stay consistent with generated terrain.
  • Feature profiles inject data-driven feature rules such as actor spawns, reusable structures, and ore-like block clusters across different generation stages.
  • Voxel graphs provide ordered fill/carve generation rules that apply chunk-wide before visible geometry is built.

Rendering, water, trees, clouds, and performance

  • Chunk Render Mode supports the classic voxel surface, an instanced visible-cube renderer, and a smooth marching-cubes surface renderer.
  • Enable Water Surface Overlay adds a separate top water surface so rivers, lakes, and oceans read more like continuous water than only stacked voxel faces.
  • Use General Biome Terrain Material lets one shared terrain material handle multiple non-water terrain layers.
  • Built-in cube trees can be enabled directly on the terrain actor and support collision, leaf drops, and fallen-leaf cubes.
  • Clouds can be enabled directly on the terrain actor, and Cloud Visual Style lets you choose between custom meshes and the built-in cube-cloud mode.
  • Use Async Chunk Generation, low-detail chunk placeholders, predictive chunk streaming, and view-frustum prioritization help smooth chunk generation and visible streaming cost.

Advanced C++ extension point

  • ModifyGeneratedChunk(FGeoForgeChunkGenerationContext&) lets a C++ subclass mutate raw chunk voxel data before mesh generation.
  • GetChunkGenerationHook() exposes a native multicast hook for advanced generation workflows.
  • If async chunk generation is enabled, avoid touching non-thread-safe UObject state inside raw generation hooks unless you handle synchronization yourself.

Documentation and support