Landscape

🧠 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.

Landscape Terrain Skill

Sub-docs available

This skill is split into the lean index (you are reading it) plus sibling sub-docs. Skills load via the engine's AgentSkillToolset (ListSkills / GetSkills) — request landscape/<section> through GetSkills, or read the sibling *.md file (it sits next to this SKILL.md on disk) directly:

Critical Rules

Valid Quad Sizes

QuadsPerSection must be one of: 7, 15, 31, 63, 127, 255 SectionsPerComponent must be 1 or 2

Common setup: QuadsPerSection=63, SectionsPerComponent=1, ComponentCount=8x8

⚠️ Performance: Landscape Creation Timeout

Creating landscapes with many components is SLOW. Python execution has a 30-second timeout.

Safe configurations (under 30s):

• ComponentCount=4x4 (253x253 resolution) — safe for throwaway/test terrains
• ComponentCount=8x8 (505x505 resolution) — can exceed 30s in a populated level (measured 67s in a level that already had another landscape); safe only in near-empty levels

Will TIMEOUT (avoid):

• ComponentCount=16x16 or larger in a populated level
• ComponentCount=36x36 or larger — too many components, takes minutes
• ComponentCount=72x72 — definitely exceeds timeout

⚠️ A timeout does NOT cancel the operation. PYTHON_EXECUTION_TIMEOUT means the tool stopped waiting — the create keeps running on the game thread and usually completes. Never blindly retry: you'd stack a second landscape with the same label (then delete_landscape removes only the first match and landscape_exists stays true, which looks like a delete failure). After a timeout, check landscape_exists(label) first. create_landscape also refuses to create a landscape whose label already exists.

⚠️ Heightmap Import: Resolution MUST Exactly Match

import_heightmap() requires the heightmap file resolution to exactly match the landscape resolution. There is NO automatic scaling. A size mismatch will fail or produce flat/corrupt terrain.

If the target landscape label does not exist, import_heightmap() now auto-creates a matching landscape at world origin with default scale (100,100,100) before importing. For real-world terrain workflows, explicitly creating the landscape first is still recommended so you can control XY/Z scale.

Landscape resolution formula: Resolution = (ComponentCount × QuadsPerSection × SectionsPerComponent) + 1

Safe performant configs (common resolutions):

⚠️ 1081×1081 is NOT a valid performant config! The only config producing 1081 is 36×36 components, 15 quads, 2 sections — which has 1296 components and will timeout. Never request or assume 1081.

Heightmap ↔ Landscape Sizing Utilities

Four Python utility functions help match heightmaps to landscapes:

✅ Recommended Workflow: Request Matching Resolution

BEST approach — request the heightmap at the exact resolution you need:

1. Decide landscape config (e.g., 8×8 components, 63 quads, 2 sections)
2. Calculate resolution: (8 × 63 × 2) + 1 = 1009
3. Use terrain_data generate_heightmap with resolution=1009 and map_size=N
   • map_size controls how many real-world km are captured (default 17.28)
   • Smaller map_size = more detail for a specific feature (e.g., 2-5 km for a single mountain)
   • Larger map_size = wider area with less per-pixel detail (e.g., 10-20 km for a region)
4. Create landscape with matching config
5. Import heightmap — sizes match perfectly

✅ Fallback Workflow: Resize After Download

If you already have a heightmap at a non-matching resolution:

1. Check dimensions: get_heightmap_dimensions(file_path)
2. Either:
   • Find a landscape config that matches: find_landscape_config_for_resolution(width, height)
   • Or resize the heightmap to match your landscape: resize_heightmap(source, target_w, target_h)
3. Create landscape / import resized heightmap

World Partition landscapes (streaming proxies)

In a World Partition level, pass world_partition_grid_size (components per proxy grid cell, e.g. 2) to create_landscape to split the landscape into ALandscapeStreamingProxy actors — the same thing the editor's New Landscape tool does in a WP world:

pythonCopy code
result = unreal.LandscapeService.create_landscape(
    unreal.Vector(0, 0, 0), unreal.Rotator(0, 0, 0), unreal.Vector(100, 100, 100),
    sections_per_component=1, quads_per_section=63,
    component_count_x=8, component_count_y=8,
    landscape_label="WPLandscape", world_partition_grid_size=2)

• The default world_partition_grid_size=0 keeps the single monolithic ALandscape (old behavior).
• The call fails with an error if the level is not World Partition — the engine's grid split is a silent no-op there, so VibeUE refuses instead of pretending.
• import_heightmap, sculpting, painting, and region edits are proxy-transparent: they resolve the parent ALandscape and fan updates out to every proxy sharing its landscape GUID. Nothing else in your workflow changes.

🚨 Save semantics: the dirty list lies — audit with get_last_landscape_write() + git status

On a World Partition landscape the engine's dirtying mode (LandscapeSettings.LandscapeDirtyingMode, default In Landscape Mode And User Triggered Changes) does not mark an edit dirty when it is made outside Landscape mode — and every VibeUE/Python edit is outside Landscape mode. The engine tracks the touched packages in an internal modified-package list instead of the normal dirty flag. The practical consequences, all measured:

• import_heightmap dirties the proxies but does not save them. You must save explicitly.
• A brush / region / semantic op (flatten_at_location, set_height_in_region, sculpt/smooth/…) can write the proxy .uasset files to disk during the edit-layer resolve while the editor's dirty list shows nothing. One flatten_at_location left 49 proxy files modified on disk with an empty dirty list. So the dirty list is not a reliable audit of a WP landscape after a brush op.
• git status is the only fully honest audit (the modified files live under Content/__ExternalActors__/...; restore an unwanted change with the editor closed via git checkout -- Content/__ExternalActors__/...).

Two tools make this auditable from Python:

pythonCopy code
import unreal
svc = unreal.LandscapeService

svc.flatten_at_location("Landscape", 0.0, 0.0, 0.0, 250.0)   # any height writer

# What did that write actually touch?
rep = svc.get_last_landscape_write()
print(rep.summary)                       # e.g. "49 proxies dirtied; 49 written to disk by the edit-layer flush (mtime changed)"
print(rep.num_proxies_dirtied, rep.num_written_to_disk, rep.b_any_written_to_disk)
for p in rep.proxies:
    print(p.package_name, "dirty:", p.b_dirty_after, "written:", p.b_written_to_disk, p.file_size_bytes)

• get_last_landscape_write() reports, per proxy package the last write touched: b_dirty_before / b_dirty_after (the unreliable flag) and b_written_to_disk — an on-disk mtime comparison bracketing the edit-layer resolve, which is the signal you can trust. num_written_to_disk / b_any_written_to_disk summarise it.

  • Caveat: the mtime probe only sees writes that complete during the MCP call (around the synchronous ForceUpdateLayersContent resolve). If the engine ever defers the on-disk save to a later editor tick, b_written_to_disk reads false even though the file changes shortly after — so git status remains the final word.

• save_landscape(label) is the deterministic, explicit save: it collects the parent ALandscape package plus every proxy sharing the landscape GUID and saves them all through UEditorLoadingAndSavingUtils::SavePackages(..., only_dirty=False) — i.e. regardless of the dirty flag. Use it after import_heightmap (which never saves), or any time you want a clean, audited flush.

pythonCopy code
res = svc.save_landscape("Landscape")
if res.b_success:
    print("saved", res.num_requested, "packages:", list(res.saved_packages))
else:
    print("save failed:", res.error_message)   # e.g. a read-only / source-controlled file

Blocky / faceted flat areas (plains)

Low-res source DEMs upsampled to landscape resolution show planar facets on flat terrain. Fixes, in order of preference:

1. resize_heightmap(..., interpolation="bicubic") — now the default; re-run the resize+import if the landscape was built with an older (bilinear) resize.
2. Increase blur_passes (20–40) on terrain_data generate_heightmap for plains-heavy regions.
3. Material-level smoothing without touching heights: derive a world-space smoothed normal in the landscape material (see landscape-materials skill) when height data must stay pixel-exact.

Landscape Scale

• Default scale (100, 100, 100) = 1 meter per unit
• Larger Z scale = taller terrain range (e.g., Z=200 doubles height range)

⚠️ When importing real-world terrain from terrain_data, ALWAYS calculate Z scale:

Copy code
z_scale = 20000 / height_scale

Do NOT hardcode Z scale. The height_scale from preview_elevation determines the correct Z scale.

Height Limits (uint16 Saturation)

The heightmap is uint16 (0–65535, midpoint 32768). Maximum world height depends on Z scale:

Formula: MaxHeight = (65535 - 32768) × (1/128) × ZScale

When sculpting pushes vertices to 0 or 65535, a saturation warning is logged. To increase range:

• Increase landscape Z scale (halves vertical resolution)
• Offset landscape Z location downward to use the full ±range

World Coordinates vs Landscape Coordinates

• Most methods accept world coordinates (WorldX, WorldY)
• get_height_in_region and set_height_in_region use landscape-local vertex indices
• Heights in set_height_in_region are world-space Z values
• Heights returned by get_height_in_region are world-space Z values

⚠️ GrassVariety Struct Properties Are Read-Only via Direct Assignment

GrassVariety (and its nested structs like PerPlatformFloat, FloatInterval, etc.) cannot be set via direct attribute assignment. You MUST use set_editor_property() for all properties.

pythonCopy code
# WRONG - raises "Property is read-only and cannot be set"
nv = unreal.GrassVariety()
nv.affect_distance_field_lighting = True
nv.grass_density.default = 50.0

# CORRECT - use set_editor_property and construct new struct instances
nv = unreal.GrassVariety()
nv.set_editor_property('affect_distance_field_lighting', True)
nv.set_editor_property('grass_density', unreal.PerPlatformFloat(default=50.0))
nv.set_editor_property('scale_x', unreal.FloatInterval(min=1.0, max=3.0))

This applies to ALL nested structs: PerPlatformFloat, PerPlatformInt, PerQualityLevelFloat, PerQualityLevelInt, FloatInterval, LightingChannels. Always construct a new struct instance with keyword args.

⚠️ Creating LandscapeGrassType Assets Requires AssetTools + Factory

LandscapeGrassType assets are NOT created via LandscapeService. Use AssetToolsHelpers with LandscapeGrassTypeFactory:

pythonCopy code
# WRONG - no such method exists
unreal.LandscapeService.create_grass_type("LGT_MyGrass", "/Game/Grass")

# CORRECT - use AssetTools + Factory
asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
factory = unreal.LandscapeGrassTypeFactory()
new_asset = asset_tools.create_asset("LGT_MyGrass", "/Game/Grass", unreal.LandscapeGrassType, factory)

⚠️ Use LandscapeMaterialService for Landscape Materials - NOT MaterialService

• CORRECT: unreal.LandscapeMaterialService.create_landscape_material("M_Terrain", "/Game/Mats")
• WRONG: unreal.MaterialService.create_material("M_Terrain", "/Game/Mats") → causes TypeError: Nativize: Cannot nativize 'MaterialCreateResult' as 'String'

MaterialService is for generic materials. Landscape materials MUST use LandscapeMaterialService.

Layer Info Objects Required

Every paint layer needs a ULandscapeLayerInfoObject asset:

1. Create with LandscapeMaterialService.create_layer_info_object()
2. ALWAYS store and use .asset_path from the result — never guess paths
3. Naming convention is LI_<LayerName> (e.g., LI_Grass, LI_Rock) — NOT Grass_LayerInfo
4. Then add to landscape with LandscapeService.add_layer(landscape_label, info.asset_path)

Material Must Be Compiled First

After creating/changing a landscape material, compile it before assigning to the landscape.

⚠️ Split Material Operations Into Separate Code Blocks

compile_material() can take minutes for complex landscape materials. NEVER combine material creation + compile + layer info creation in one code block — it WILL timeout.

Do this in separate steps:

1. Block 1: Create material, add blend nodes, add layers, connect, save
2. Block 2: compile_material() (this is slow)
3. Block 3: Create layer info objects, assign to landscape

⚠️ Common Mistakes to Avoid

Related Skills

• landscape-materials: Simple landscape materials with LandscapeLayerBlend nodes. Good for prototyping with 2-5 layers.
• landscape-auto-material: Production-quality auto-materials using material functions, Runtime Virtual Textures, and material instances (Real_Landscape paradigm). Good for shipping quality.

When you need to create or modify the material applied to a landscape, load the appropriate material skill through GetSkills (AgentSkillToolset):

• For simple materials: load landscape-materials
• For production auto-materials: load landscape-auto-material

NOTE: For landscape material, texture, and layer blending operations, use LandscapeMaterialService (load the landscape-materials or landscape-auto-material skill).

Sample scripts (run via execute_python_code)

• scripts/sculpt_terrain.txt — create a landscape and sculpt procedural mountain/valley features.

Additional gotchas

• On a World Partition landscape, verify every sculpt and every reader with a line_trace_single grid; the only safe write path is export_heightmap -> stamp in Python -> import_heightmap. Never synthesise a flat baseline — a flat-plus-pit import erases carved features.
• Pixel mapping: origin is the proxy min corner, world = min + px * scale, worldZ = (H - 32768) * 100/128, no row flip; check against a known trace height before writing.
• import_heightmap does not write proxies to disk — call save_landscape (or save_packages the Landscape and every proxy). Use get_last_landscape_write to see what changed, since the dirty list is unreliable right after landscape calls.
• flatten_at_location and set_height_in_region read and write the same edit layer now, so a region write stays inside its brush on World Partition; apply_erosion was always safe.
• load_level from Python leaves all WP cells unloaded for the rest of the session, and create_landscape run headless produces a broken landscape (zero heights, no collision).
• Delete a landscape together with its streaming proxies via delete_landscape(include_proxies=True); destroying proxy actors by hand crashes the editor.
• The edit-layer merge can re-surface old garbage after a later merge (a brush spawn, apply_splines_to_landscape); re-verify landmarks by trace after any landscape-touching op.
• Spawning any WaterBody auto-spawns a WaterBrushManager (affects_landscape defaults True) that adds a "Water" edit layer and poisons the terrain; flip that CDO default first and delete any spawned manager. WaterZone.zone_extent is on the actor; the river/lake seam material is lake_transition_material; target_wave_mask_depth is the still-water knob.