terrain-data

name	terrain-data
display_name	Real-World Terrain
description	Generate heightmaps, map reference images, and water feature splines (rivers, lakes, oceans) from real-world geographic data (terrain_data tool). Use when the user asks to build terrain from a real location/coordinates, download a real-world heightmap, or add rivers/lakes/oceans from map data. Downloads Mapbox tiles server-side and produces UE5-compatible heightmaps + landscape splines.
keywords	["terrain","heightmap","real world","real-world","elevation","topography","satellite","map image","cities skylines","mapbox","import heightmap","landscape import","mount fuji","san francisco","real terrain","geographic","coordinates","latitude","longitude","topo","water","river","lake","ocean","waterway","stream","canal","water features","spline","river spline","lake spline"]

🧠 Brains complement: IF an unreal-engine-skills-manager tool (external MCP) exists in this session, call it with {action: "load", skill: "landscape-and-foliage"} for UE domain knowledge on this topic — correct APIs, architecture, best practices — and treat it as the rubric for any review / "best practices" question. If no such tool is available (e.g. running under Claude Code or Codex without that MCP), skip this line entirely and proceed with this skill alone — do NOT attempt the call.

Real-World Terrain Skill

Generates heightmaps and water feature splines from real geographic coordinates via the terrain_data MCP tool. The tool downloads Mapbox tiles server-side and writes UE5-compatible heightmaps + landscape splines into the project's Saved/Terrain/ folder — no API key or chat configuration is required.

Workflow

Heightmap (always run first)

1. preview_elevation — fetch elevation stats + suggested settings. Returns suggestedZScale, suggestedXYScales (resolution → XY scale), height range.
2. generate_heightmap — generate the 16-bit PNG using suggested settings
3. (optional) get_map_image — satellite/topo reference image for the same area
4. attach_image — attach the satellite image so you can see the terrain colors and features for material/painting decisions
5. Import into UE5 using the landscape skill

⚠️ CRITICAL — Landscape Scale: When creating the landscape, use suggestedXYScales[resolution] from step 1 as the X and Y scale. Do NOT use the default value of 100. Use suggestedZScale for the Z scale. Example: scale=unreal.Vector(suggestedXYScales["1009"], suggestedXYScales["1009"], suggestedZScale)

Water features (after heightmap is imported)

6. get_water_features — fetch rivers, lakes, and oceans for the same lng/lat/map_size. Saves full JSON to Saved/Terrain/ and returns a compact summary with the file path.
7. Read the saved JSON file: json_str = open(file_path).read()
8. Water bodies use ue5_rings, waterways use ue5_points. Both are origin-centered.

---

Test Prompts

Create a landscape from the terrain around Mount Fuji

Generate a heightmap for San Francisco at coordinates -122.4194, 37.7749

Build a real-world landscape from the Swiss Alps near Zermatt (lng=7.7480, lat=46.0207)

Get the terrain around the Grand Canyon and make a landscape

Generate heightmap for Tokyo at 139.6917, 35.6895 with a satellite reference image

---

Step-by-Step Example (Mount Fuji)

Step 1 — Preview elevation

terrain_data(action="preview_elevation", lng=138.7274, lat=35.3606)

Response:

{
  "min_height": 340.0,
  "max_height": 3776.0,
  "height_range": 3436.0,
  "suggested_base_level": 340,
  "suggested_height_scale": 27,
  "suggestedZScale": 741,
  "suggestedXYScales": { "505": 3429, "1009": 1714, "2017": 857, "4033": 429, "8129": 213 },
  "tile_zoom": 13,
  "tile_count": 9
}

Use suggestedXYScales["1009"] (or whichever resolution you chose) as the X and Y scale when calling create_landscape. Use suggestedZScale for the Z scale.

Step 2 — Generate heightmap using suggested values

terrain_data(
  action="generate_heightmap",
  lng=138.7274, lat=35.3606,
  base_level=340,
  height_scale=27,
  format="png"
)

Response:

{
  "success": true,
  "file": "C:/Project/Saved/Terrain/heightmap_35.3606_138.7274.png",
  "min_height_m": 340.0,
  "max_height_m": 3776.0,
  "dimensions": "1081x1081"
}

Step 3 — Get satellite reference image

terrain_data(
  action="get_map_image",
  lng=138.7274, lat=35.3606,
  style="satellite-v9"
)

Response:

{
  "success": true,
  "file": "E:/Project/Saved/Terrain/map_satellite_v9_35.3606_138.7274.png",
  "style": "satellite-v9",
  "size_bytes": 1981147
}

Step 3b — Attach satellite image for vision analysis

⚠️ CRITICAL: After downloading a satellite image, ALWAYS attach it so you can see the terrain colors and features. This lets you make informed decisions about material layers and painting.

attach_image(file_path="E:/Project/Saved/Terrain/map_satellite_v9_35.3606_138.7274.png")

attach_image is a tool call (like terrain_data), NOT a Python function. Do NOT put it inside execute_python_code. Call it directly as a tool. If no attach_image tool is available in your session, skip this step and proceed using the saved file path returned by get_map_image.

After attaching, you will see the satellite image in your next response. Use it to:

• Identify terrain features (rock, grassland, water, sand, forest, urban)
• Choose appropriate material layer names and colors
• Design accurate procedural painting rules (height/slope thresholds)
• Match real-world color distribution to layer weights

Step 4 — Import into UE5

Use the landscape skill to import the heightmap file:

• Component setup: QuadsPerSection=63, SectionsPerComponent=2, ComponentCount=8x8 → 1009×1009 resolution
• X and Y scale: Use suggestedXYScales["1009"] from preview (e.g. 1714 for a 17.28km map). Do NOT use the default 100 — that makes the landscape ~17x too small!
• Z scale: Use suggestedZScale from preview (e.g. 741 for Mount Fuji)
• File: the .png path returned in step 2

Example:

result = unreal.LandscapeService.create_landscape(
    location=unreal.Vector(0, 0, 0),
    rotation=unreal.Rotator(0, 0, 0),
    scale=unreal.Vector(1714, 1714, 741),  # XY from suggestedXYScales["1009"], Z from suggestedZScale
    sections_per_component=2,
    quads_per_section=63,
    component_count_x=8,
    component_count_y=8,
    landscape_label="MyLandscape"
)

---

Parameters Reference

generate_heightmap

Parameter	Default	Notes
lng / lat	required	Decimal degrees. Positive = East/North
format	png	png = 16-bit grayscale, raw = binary, zip = PNG + info
map_size	17.28	km — Cities: Skylines standard
base_level	0	Use suggested_base_level from preview
height_scale	100	Use suggested_height_scale from preview
water_depth	40	Cities: Skylines water units
gravity_center	0	0=off, 2=N, 4=E, 6=S, 8=W (tilts terrain for water flow)
level_correction	0	0=none, 2=flatten coastlines, 3=aggressive
blur_passes	10	Adjust per terrain character! 5–10=rugged, 15–25=hills, 25–40=smooth/flat. See Terrain Character Guide
plains_height	140	Meters — threshold between plains and mountains
save_path	auto	Saves to <ProjectDir>/Saved/Terrain/ by default

get_map_image styles

Style	Description
satellite-v9	Aerial imagery (best for landscape texturing)
outdoors-v11	Topo with trails and contours
streets-v11	Street map
light-v10 / dark-v10	Minimal

---

UE5 Landscape Import Settings

Valid Resolutions — Always Pass resolution=N

⚠️ Never use the default 1081×1081 for UE landscapes — it requires 36×36 components and will timeout. Always pass resolution= matching your landscape config.

resolution=	Components	Quads	Sections	km at UE scale=100
505	8×8	63	1	~0.5 km
1009	8×8	63	2	~1.0 km
1009	16×16	63	1	~1.0 km
2017	16×16	63	2	~2.0 km
4033	32×32	63	2	~4.0 km
8129	32×32	127	2	~8.1 km

"km at scale=100" is the UE world size when landscape XY scale = 100 cm/quad (default). Adjust scale to match real geography (see below).

Matching Real-World Scale

terrain_data's map_size (default: 17.28 km) controls the geographic area captured. To make the UE landscape match actual geography:

UE XY Scale (cm/quad) = (map_size_km × 100,000) / (resolution − 1)

Example: map_size=20, resolution=2017 → (20 × 100,000) / 2016 ≈ 992 cm/quad (~9.9 m/quad)

Set this as the landscape's X and Y scale when creating it.

Format and Z Scale

• Format: 16-bit grayscale PNG
• Z Scale: 20000 / height_scale cm — e.g., height_scale=27 → Z scale ≈ 741

⚠️ ALWAYS calculate Z Scale from height_scale. Do NOT guess. Use this formula when creating the landscape:

z_scale = 20000 / height_scale

Derivation: pixel encoding is pixel = elevation_m × heightScale × 64 / 100 and UE interprets height_cm = pixel × z_scale / 128. Setting height_cm = elevation_m × 100 (meters→cm) gives z_scale = 20000 / heightScale.

height_scale	Z Scale	Terrain Type Example
27	741	Tall mountains (Mt. Fuji, Alps)
50	400	Moderate mountains (Appalachians)
100	200	Hills, canyons (Grand Canyon)
150	133	Low hills, mesas
200	100	Gentle rolling terrain
250	80	Very flat terrain, gentle domes

For Cities: Skylines, export as PNG and import via the standard heightmap importer (1081 default is fine there).

---

Terrain Character Guide

⚠️ CRITICAL: The suggested_height_scale from preview_elevation maximizes detail, but also amplifies noise. You MUST adjust blur_passes based on the terrain character.

Identifying Terrain Character

After preview_elevation, look at the height_range and think about what the terrain actually looks like:

height_range	suggested_height_scale	Terrain Character	blur_passes
> 2000m	Low (< 50)	Rugged mountains — keep default blur	5–10
500–2000m	Moderate (50–100)	Mixed terrain — moderate smoothing	10–15
100–500m	High (100–200)	Hills/mesas — needs more smoothing	15–25
< 100m	Very high (200–250)	Flat/gentle — needs heavy smoothing	25–40

Smooth vs Rugged Terrain

Smooth terrain (granite domes, rolling hills, plains, gentle slopes):

• Use higher blur_passes (20–40) to remove data noise
• The high height_scale amplifies every pixel of noise — smoothing counteracts this
• Examples: Enchanted Rock, Uluru, sand dunes, prairies

Rugged terrain (jagged peaks, canyons, volcanic craters):

• Use lower blur_passes (5–10) to preserve detail
• Lower height_scale means less noise amplification, so less smoothing needed
• Examples: Grand Canyon, Matterhorn, Iceland lava fields

Common Mistake: Jagged Smooth Terrain

If you get a terrain that looks jagged/spiky when the real place is smooth:

1. The height_scale was too high without enough blur_passes
2. Fix: Re-generate with blur_passes=30 or higher
3. Also check: Z scale should be 20000 / height_scale, NOT an arbitrary value like 200

---

Water Features Reference

get_water_features

Fetches waterways and water bodies for a map area using the same Mapbox Vector Tile source as the heightmap. Use the exact same lng, lat, and map_size as your heightmap call.

terrain_data(action="get_water_features", lng=-105.0, lat=39.7, map_size=17.28)

Response includes:

• file — path to the saved JSON file (e.g. Saved/Terrain/water_features_42.9720_-71.3480_10km.json)
• num_waterways / num_water_bodies — counts
• waterway_class_breakdown — object with class counts, e.g. {"stream": 191, "river": 26, "ditch": 12}
• waterways[] — summary of each waterway: name, class, estimated_width_m, num_points
• water_bodies[] — summary of each water body: name, class, num_ring_points
• message — instructions on how to use the saved file, coordinate system info
• ue5_coordinate_note — critical info about coordinate offset for water planes

The saved JSON file contains the full data with:

• waterways[] — rivers, streams, canals. Each has name, class, estimated_width_m, points (lng/lat array), ue5_points (array of {x, y, z} objects in UE5 coords)
• water_bodies[] — lakes, ponds, oceans. Each has name, class, rings (lng/lat array of arrays), ue5_rings (array of arrays of {x, y, z} objects in UE5 coords)

⚠️ CRITICAL FIELD NAMES:

• Waterway positions: ue5_points (NOT points — those are lng/lat)
• Water body polygons: ue5_rings (NOT polygon or ring)
• Waterway type: class (NOT waterway_class or type)

Coordinate system

ue5_points and ue5_rings are landscape-center-relative (origin-centered):

• Map geographic center = (0, 0, Z) in UE5 space
• +X = East, +Y = North, 1 meter = 100 UU

---

Troubleshooting

Issue	Fix
429 rate limit	The Mapbox tile source is rate-limited — wait and retry, or reduce request frequency
Flat heightmap	height_range < 50m — use height_scale: 250 for detail
Clipped mountains	Lower height_scale or increase base_level
Jagged/spiky terrain	Increase blur_passes (20–40 for smooth terrain) and check Z scale formula
Terrain doesn't match real place	Check terrain character guide — smooth places need high blur_passes
Timeout	Large map sizes at high zoom may hit Vercel's 10s limit — try smaller map_size
No waterways returned	Area may have no mapped water features (desert, urban grid) — check satellite image
Landscape too small	You used XY scale=100 (default) instead of the correct value from suggestedXYScales. Recreate with the correct scale
Black screenshots after camera move	Camera inside terrain. Use ActorService.get_actor_view_camera() to frame from TOP view instead of guessing Z height
Water features timeout	PBF tile fetch uses 45s timeout — large map_size at high zoom may still be slow
Field name errors	Use ue5_points (not points), ue5_rings (not polygon), class (not waterway_class)