GeoForgeRuntime DOC

GeoForgeRuntime - Block-Based Cubic World

GeoForgeRuntime is a runtime Unreal Engine plugin for creating block-based cubic terrain with streaming, digging, terrain placement, reusable voxel structure assets, biome profile assets with preview editing, built-in cube trees, built-in cube clouds, and terrain save/load support. The included editor module also adds viewport terrain-authoring tools, custom asset editors, and preview workflows for structure and biome content.

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 and streams the terrain.
  • GeoForgeTerrainBlueprintLibrary exposes the Blueprint utility nodes for tracing, digging, terrain placement, generation overrides, structure stamping, and save/load.
  • GeoForgeTerrainSaveGame is the SaveGame type used by the quick-save Blueprint helpers.
  • GeoForgeBiomeProfile is a reusable data asset for authoring biome masks, preview colors, and macro-region layout settings.
  • GeoForgeVoxelStructure is a reusable data asset for authoring relative voxel edits that can be stamped into terrain.
  • GeoForgeVoxelStructureStampActor is an editor helper actor for previewing and stamping structure assets into a target terrain actor.

Editor module tools

  • GeoForge Terrain editor mode adds viewport authoring tools for placing voxels, removing voxels, and stamping structure assets directly onto GeoForge terrain.
  • The terrain mode exposes brush radius, material override, surface offset, active structure, and structure rotation settings, and it shows viewport preview feedback before you click.
  • GeoForge Biome Profile Editor adds a Noise Mask Preview tab plus a Details tab. The preview uses the same Region / Climate / Vegetation / Frost channels as runtime and blends the two strongest biome masks through transition areas.
  • GeoForge Voxel Structure Editor adds a preview viewport, structure details, and a Brush & Conversion panel for add/remove brush editing, clearing, and static-mesh voxelization.
  • The editor module also registers a GeoForge asset category and Content Browser factories for creating GeoForgeBiomeProfile and GeoForgeVoxelStructure assets.
  • The editor module 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.
  • Set the terrain preset you want, such as Endless Flatlands, Endless Mountains, or Endless Seeded Terrain.
  • Adjust block size, chunk size, chunk height, ground level, seed, and noise settings in the Details panel.
  • Assign your terrain materials if you want custom visuals for surface, soil, rock, deep rock, water, sand, or snow.
  • If you want profile-driven biome regions, create or assign a GeoForgeBiomeProfile, enable Use Biome Regions, and tune the biome profile asset.
  • 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 and control the streamed terrain.
  • If no streaming source actor is assigned, the plugin uses the player pawn at runtime.

Useful terrain settings

  • World Preset controls the overall terrain style.
  • View Distance In Chunks controls how far terrain remains loaded around the streaming source.
  • Chunk Size In Cells controls terrain chunk width and depth.
  • Chunk Height In Cells controls the vertical terrain range.
  • Cell Size controls the size of each block in Unreal units.
  • World Seed keeps terrain generation deterministic.
  • Use Biome Regions enables profile-driven biome regions for endless seeded terrain.
  • Biome Profile assigns the biome data asset used for profile-driven biome masks and macro layout.
  • Auto Rebuild In Editor is useful while previewing biome-profile edits in editor.
  • bEnableBuiltInCubeTrees enables built-in block-style trees.
  • bEnableClouds enables streamed cloud generation.
  • Cloud Visual Style switches the cloud system between custom cloud meshes and the built-in cube-cloud mode.
  • bPersistEditedCellsAcrossStreaming keeps terrain edits when chunks unload and reload.

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 final 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: Create exact one-block digging

  • From your player character, trace forward using Trace Terrain 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 3: 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 4: Place terrain back into the world

  • Use Place Terrain Cube when you want to add one exact cube near a target world location.
  • Use Add Terrain when you want to add either one exact cube or a larger spherical area.
  • This is useful for builders, repair tools, gameplay abilities, or voxel-style construction.

Use case 5: 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 6: 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 7: Enable built-in cube trees and clouds

  • Enable bEnableBuiltInCubeTrees if you want automatic block-style tree placement.
  • Enable bEnableClouds if you want cloud generation.
  • Adjust density, scale, style, and collision settings in the Details panel.
  • Press Play to see the decorative systems appear with the streamed terrain.

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, and layout settings.
  • Assign the profile to your terrain actor and enable Use Biome Regions.
  • Use the Noise Mask Preview to author more natural macro regions with soft transitions. It uses the same Region / Climate / Vegetation / Frost channels as runtime generation.
  • The default biome set includes Plains, Desert, Mountains, Forest, Snow, Badlands, Tundra, Swamp, and Savanna.

Use case 9: 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, or static-mesh voxelization 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.

Use case 10: Use the GeoForge Terrain editor mode

  • Activate the GeoForge Terrain editor mode in Unreal Editor.
  • Choose Place Voxel, Remove Voxel, or Stamp Structure.
  • Set brush radius, surface offset, and optional material override 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.
  • 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 nodes

  • Trace Terrain From Actor View traces forward from an actor view and returns whether GeoForge terrain was hit.
  • 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.
  • Place Terrain Cube adds one exact cube to the nearest empty valid cell.

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 From Actor View + Dig Terrain for mining and terrain interaction.
  • Add Terrain + Place Terrain Cube for repair tools and voxel-style building.
  • Set Terrain Generation Voxel for single persistent generation edits.
  • 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 profiles

  • Biome profiles use Region, Climate, Vegetation, and Frost channels to resolve biome masks.
  • Layout settings add continent-scale climate, province-style regions, and macro/local warping for less repetitive infinite worlds.
  • Transition zones blend more softly between neighboring biome masks instead of switching instantly.
  • Tundra, Swamp, and Savanna are included as default authored biome definitions alongside the original core set.

Built-in trees and clouds

  • Built-in cube trees can be enabled directly on the terrain actor.
  • 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.
  • Both systems are optional and controlled in the actor Details panel.
  • You can assign custom materials where supported for a more specific visual style.

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