// getting started

Build your first location

GeoScape fetches OpenStreetMap buildings & roads and global elevation for a bounding box, then generates a to-scale Landscape with Nanite buildings and roads. From install to a built city in a few minutes.

Requirements

Unreal Engine 5.8, with the Geometry Scripting plugin (enabled automatically as a dependency).
A C++-capable project (Visual Studio toolchain on Windows).
Internet access at author time (for the fetch). Offline? Use the bring-your-own-GeoJSON path with a local elevation source.

Install & enable

Drop in the plugin

Copy the plugin to YourProject/Plugins/GeoScape/.

Build the editor

Right-click the .uproject → Generate Visual Studio project files, then build the Development Editor target.

Enable it

Edit → Plugins → GeoScape, enable, and restart the editor.

Build a location

Open a fresh empty level

File → New Level → Empty Level. GeoScape drapes geometry onto the terrain with downward traces, so it needs the Landscape resident, a non–World-Partition level is ideal for the build pass.

Open the GeoScape panel

Tools → GeoScape — Real-World City Builder (or Window → GeoScape).

Enter a location

Set Center Latitude / Longitude (grab them by right-clicking a spot in Google Maps), an Area Size (km), and Terrain Detail. Tick the layers you want: Terrain, Buildings, Roads.

Press Build Location

The progress bar reports each stage. When it finishes, the terrain and city are in your level. Clear removes everything a build generated.

Tip: Start small, a 0.5–2 km area in a dense city center, to see results fast. Larger areas take longer to fetch and build.

Settings

Setting	Meaning
Center Latitude / Longitude	WGS84 point the area is centered on (e.g. `-33.9249, 18.4241`).
Area Size (km)	Side length of the square region. Grows the landscape and fetch time.
Terrain Detail (m/vertex)	Landscape vertex spacing. Smaller = finer terrain, larger landscape.
Terrain / Buildings / Roads	Which layers to generate. Any combination.

Blueprint & Python API

Everything the panel does is on the GeoScapeSubsystem editor subsystem.

import unreal
sub = unreal.get_editor_subsystem(unreal.GeoScapeSubsystem)
# latitude, longitude, area_km, terrain_detail_m, terrain, buildings, roads
sub.build_location(-33.9249, 18.4241, 1.0, 4.0, True, True, True)
sub.is_busy()                    # True while a build runs (one at a time)
sub.clear_generated("GeoScape")  # remove generated actors, returns count

// C++
UGeoScapeSubsystem* Sub = GEditor->GetEditorSubsystem<UGeoScapeSubsystem>();
Sub->BuildLocation(40.7128, -74.0060, 2.0);   // Manhattan, 2 km

The build is asynchronous (HTTP fetch) and completes on the game thread, so actors spawn safely. Progress and results are written to the Output Log with a [GeoScape] prefix.

Data sources & bring your own

GeoScape ships pointed at the public OpenStreetMap Overpass API and a global terrain-RGB elevation source. Both are configurable on the build request, so you can use a private mirror or a commercial provider for production and bulk work.

It also parses your own data: a generic GeoJSON FeatureCollection (Polygon/MultiPolygon buildings, LineString/MultiLineString roads) and Overpass JSON. A configurable field mapping tells GeoScape which properties carry height, storeys, width, and lanes, so any provider's schema resolves correctly.

World Partition & HLODs

For large areas, build into a normal level, then run the standard WorldPartitionConvertCommandlet and WorldPartitionHLODsBuilder. Keep the Landscape always-loaded (Is Spatially Loaded = false) so distant terrain stays visible for establishing shots while buildings and roads stream by cell. Nanite handles building/road LOD automatically.

Data licensing

GeoScape's code is what you license (free for noncommercial use; commercial license separate). The map data it downloads is not ours and carries its own terms:

OpenStreetMap buildings & roads — © OpenStreetMap contributors, under the Open Database License (ODbL). Attribution and share-alike obligations apply to anything you distribute.
Elevation — the AWS Terrain Tiles open dataset (public-domain sources, aggregated). Attribution varies by region.

Respect each service's usage policy and rate limits, the public Overpass API is shared. GeoScape does not redistribute map data; it fetches it at author time to your machine.

Get GeoScape Back to home