Foliage

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

Foliage & Vegetation Skill

Critical Rules

Mesh Path Required

All placement methods require a valid UStaticMesh or UFoliageType asset path. Use discover_python_class('unreal.FoliageService') to see available methods.

Surface Trace

All scatter/add methods trace downward to find the ground surface. If no surface is hit (e.g., position is outside the landscape bounds), that instance is rejected. Check instances_rejected in the result.

Foliage Type Auto-Creation

When you pass a UStaticMesh path, the service auto-creates a transient UFoliageType internally. For persistent, reusable foliage types with custom properties, use create_foliage_type() first.

World Partition Levels

On a World Partition level the engine keeps foliage in one foliage actor per grid cell, and the service places, lists, counts and removes through those cell actors. There the foliage type must be an asset: a mesh path uses <Mesh>_FoliageType next to the mesh, or the one other foliage type asset for that mesh (several: the call asks for a foliage type path), and creates <Mesh>_FoliageType when there is none, saved only when the call places something and refused while PIE runs. A call that would touch a cell whose foliage actor exists but is not loaded fails and changes nothing: load that region first. Placement only counts the cell actor of the editor's current data layer / content bundle context, as the engine does: an unloaded cell actor of another data layer does not block placing into that cell. Builds that do this define the read-only console variable vibeue.Foliage.WorldPartitionCells.

Seed for Reproducibility

Use the seed parameter to get reproducible scatter patterns. Same seed + same parameters = same layout. Use seed=0 for random.

Layer-Aware Placement Requires Landscape

scatter_foliage_on_layer() requires:

1. A valid landscape name/label
2. A painted layer on that landscape
3. Layer weight threshold (0.0-1.0) — only places where weight exceeds threshold

If you get instances_added=0 with instances_rejected ≈ 4× requested, every candidate failed the surface trace or the weight check. Before blaming the threshold, check geometry:

• The scatter circle must overlap the painted part of the named landscape. A landscape is corner-anchored — created at (0,0) it spans (0,0)→(+50400,+50400) for 505 res @ scale 100, so a scatter "around (0,0)" is 3/4 off-landscape.
• Verify weights at a few candidate points first: unreal.LandscapeService.get_layer_weights_at_location(label, x, y).
• If another landscape/mesh overlaps the area at a higher Z, the surface trace hits that surface instead — instances land on the wrong surface or get rejected. Paint a larger area or center the scatter where only the target landscape exists.

⚠️ Common Mistakes to Avoid

Return Types - EXACT Properties

FFoliageScatterResult (from scatter_foliage, scatter_foliage_rect, add_foliage_instances, scatter_foliage_on_layer)

FFoliageRemoveResult (from remove_foliage_in_radius, remove_all_foliage_of_type, clear_all_foliage)

VibeUEFoliageTypeInfo (from list_foliage_types)

FFoliageTypeCreateResult (from create_foliage_type)

FFoliageQueryResult (from get_foliage_in_radius)

FFoliageInstanceInfo (individual instance data)

Workflows

Quick Scatter Trees

pythonCopy code
import unreal

result = unreal.FoliageService.scatter_foliage(
    "/Game/Meshes/SM_Tree_01",
    0.0, 0.0,     # center X, Y
    5000.0,        # radius
    200,           # count
    min_scale=0.8,
    max_scale=1.2,
    seed=42
)
if result.success:
    print(f"Placed {result.instances_added}/{result.instances_requested}")
    print(f"Rejected: {result.instances_rejected}")

Create Foliage Type + Scatter

pythonCopy code
import unreal

# Step 1: Create a reusable foliage type with custom properties
ft = unreal.FoliageService.create_foliage_type(
    mesh_path="/Game/Meshes/SM_Pine_Tree",
    save_path="/Game/Foliage",
    asset_name="FT_PineTree",
    min_scale=0.7,
    max_scale=1.3,
    align_to_normal=True,
    align_to_normal_max_angle=30.0,
    ground_slope_max_angle=40.0,
    cull_distance_max=25000.0
)
if ft.success:
    print(f"Created: {ft.asset_path}")

    # Step 2: Scatter using the foliage type
    result = unreal.FoliageService.scatter_foliage(
        ft.asset_path, 0.0, 0.0, 8000.0, 500, seed=42)

Scatter on Paint Layer

pythonCopy code
import unreal

# Place grass clumps only where the "Grass" paint layer is dominant
result = unreal.FoliageService.scatter_foliage_on_layer(
    "/Game/Meshes/SM_Grass_Clump",
    "MyTerrain",            # landscape name
    "Grass",                 # layer name
    1000,                    # count
    min_scale=0.5,
    max_scale=1.5,
    layer_weight_threshold=0.6,
    seed=99
)
print(f"Placed {result.instances_added}, rejected {result.instances_rejected}")

Scatter in Rectangle

pythonCopy code
import unreal

result = unreal.FoliageService.scatter_foliage_rect(
    "/Game/Meshes/SM_Bush",
    -5000.0, -5000.0,  # min X, Y
    5000.0, 5000.0,     # max X, Y
    300,                 # count
    min_scale=0.5,
    max_scale=1.0,
    seed=7
)

Place at Specific Locations

pythonCopy code
import unreal

locations = [
    unreal.Vector(0, 0, 0),
    unreal.Vector(500, 500, 0),
    unreal.Vector(-500, 500, 0),
    unreal.Vector(500, -500, 0),
    unreal.Vector(-500, -500, 0),
]

result = unreal.FoliageService.add_foliage_instances(
    "/Game/Meshes/SM_Tree_01",
    locations,
    min_scale=1.0,
    max_scale=1.0,
    align_to_normal=True,
    random_yaw=True,
    trace_to_surface=True
)

Multi-Type Forest

pythonCopy code
import unreal

configs = [
    ("/Game/Meshes/SM_Oak",   300, 0.8, 1.2),
    ("/Game/Meshes/SM_Pine",  200, 0.7, 1.3),
    ("/Game/Meshes/SM_Birch", 100, 0.6, 1.0),
    ("/Game/Meshes/SM_Bush",  400, 0.4, 0.8),
]

for mesh, count, min_s, max_s in configs:
    result = unreal.FoliageService.scatter_foliage(
        mesh, 0.0, 0.0, 10000.0, count,
        min_scale=min_s, max_scale=max_s, seed=42)
    print(f"{mesh}: {result.instances_added} placed")

List and Query

pythonCopy code
import unreal

# List all foliage types in the level
types = unreal.FoliageService.list_foliage_types()
for ft in types:
    print(f"{ft.foliage_type_name}: {ft.instance_count} instances ({ft.mesh_path})")

# Get count for a specific type
count = unreal.FoliageService.get_instance_count("/Game/Meshes/SM_Tree_01")
print(f"Tree count: {count}")

# Query instances in a region
query = unreal.FoliageService.get_foliage_in_radius(
    "/Game/Meshes/SM_Tree_01", 0.0, 0.0, 2000.0, max_results=50)
for inst in query.instances:
    print(f"  [{inst.instance_index}] at {inst.location}")

Remove Foliage

pythonCopy code
import unreal

# Remove trees from a building site
result = unreal.FoliageService.remove_foliage_in_radius(
    "/Game/Meshes/SM_Tree_01", 2000.0, 3000.0, 500.0)
print(f"Removed {result.instances_removed}")

# Remove ALL instances of one type
result = unreal.FoliageService.remove_all_foliage_of_type("/Game/Meshes/SM_Bush")

# Nuclear option: remove everything
result = unreal.FoliageService.clear_all_foliage()
print(f"Cleared {result.instances_removed} total instances")

Check Existence

pythonCopy code
import unreal

# Does the mesh/foliage type exist as an asset?
if unreal.FoliageService.foliage_type_exists("/Game/Meshes/SM_Tree_01"):
    print("Asset exists")

# Are there any instances of this type in the level?
if unreal.FoliageService.has_foliage_instances("/Game/Meshes/SM_Tree_01"):
    print("Instances exist in level")

Sample scripts (run via execute_python_code)

• scripts/scatter_foliage.txt — create a foliage type from a mesh and scatter instances onto the surface.