map-blockout

🧠 Brains complement: IF an unreal-engine-skills-manager tool (external MCP) exists in this session, call it with {action: "load", skill: "levels-and-world-partition"} 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.

Procedural FPS Map Blockout Skill

Take a VibeUE-generated landscape (heightmap + paint layers) and turn it into a fully validated, AAA-style open-world FPS map blockout — roads, POIs, fields, forests/treelines, railway, bridges — then materialize the plan as real engine geometry. Quality benchmark is Arma / Squad.

The design pipeline is gated: every stage runs ordered pass/fail checks against the authoritative spec at docs/design/map-designer-spec.md. You may not advance until all checks PASS. On failure, fix the offending element and re-run the stage.

Sub-docs available

Skills load via the engine's AgentSkillToolset (ListSkills / GetSkills). To pull a sub-doc, request map-blockout/<section> through GetSkills. The sibling *.md files also sit next to this SKILL.md on disk and can be read directly.

Critical Rules

The gate is non-negotiable

Each stage's Gate.bAllPassed must be true before advancing. The orchestrator (run_full_pipeline) stops at the first failing gate and surfaces the failing check name + message in the returned struct. Inspect Gate.Checks to know what to repair.

Run Stage 0 first

run_full_pipeline_for_landscape is the one-call convenience. Otherwise:

1. unreal.MapBlockoutService.export_landcover_grid(landscape_label, grid_n=120)
2. Pass the result + config to run_full_pipeline

export_landcover_grid reads every paint layer on the source landscape plus the heightmap, returns a normalized grid in one native call — no PNG round-trip and no host-Python pre-processing step.

Map your paint layers to design categories

The spec assumes 4 logical categories: crop, soil, flood (water), forest. You must tell the service which layer names on the source landscape play each role:

cfg = unreal.MapBlockoutConfig()
cfg.layers.crop   = "Crop"     # name on the landscape
cfg.layers.flood  = "Water"
cfg.layers.forest = "Forest"
cfg.layers.soil   = "Soil"

Empty flood is allowed — water is derived from a low-elevation percentile of the heightmap.

Output folder is named after level_name

<Project>/Saved/MapBlockout/<level_name>/
  Stage1_Roads.png                                   <- cumulative snapshot
  Stage2_Roads_POIs.png
  Stage3_Roads_POIs_Fields.png
  Stage4_Roads_POIs_Fields_Foliage.png
  Stage5_Roads_POIs_Fields_Foliage_Rail.png
  CombinedFoliageAndMap.png                          <- final, with color key
  FoliageHeatMap.png                                 <- trees + fields + scrub
  MapHeatMap.png                                     <- roads + buildings + rail + bridges

All 8 files are required for delivery. The Final Pass refuses to ship if any upstream gate has unresolved failures.

Color chart is authoritative

Every rendered output uses the MapDesigner color chart (see stage-rules.md). Constants live in MapBlockoutImage::Colors::* (C++). Do not invent new colors — the heatmap + combined map are required deliverables and must match.

The Color Key must NOT cover the map

Top-right panel. If the panel rect intersects the map area, the stage fails its "Color Key" check. The renderer enforces this — but if you write a custom renderer, honor the rule.

Two-Phase Workflow

Phase 1 — design the plan (CPU, masks + polylines, no engine geometry):

import unreal
S = unreal.MapBlockoutService

cfg = unreal.MapBlockoutConfig()
cfg.level_name = "Verkhova"
cfg.layers.crop, cfg.layers.forest = "Crop", "Forest"
cfg.layers.flood = "Water"

result = S.run_full_pipeline_for_landscape("Landscape1", cfg)
if not result.success:
    # Inspect result.final_state.<stage>.gate.checks for the failing entry
    print(result.error_message)
else:
    print("Wrote:", result.output_files)

Phase 2 — materialize into the level:

S.materialize_roads_as_splines(result.final_state.stage1_roads, "Landscape1")
S.materialize_fields_as_paint(result.final_state.stage3_fields, "Landscape1", "Crop")
S.materialize_pois_as_actors(result.final_state.stage2_pois, "/MapBlockout/POIs/")
S.materialize_forest_as_foliage(result.final_state.stage4_foliage,
    "/Game/Foliage/FT_Forest", "/Game/Foliage/FT_Treeline", "/Game/Foliage/FT_Scrub")
S.materialize_railway_and_bridges(result.final_state.stage5_railway, "Landscape1")

Status

Fully implemented — every stage (Roads, POIs, Fields, Foliage, Railway/Bridges), the Final Pass, the renderers, and the materializers are live in C++. The full pipeline has been verified end-to-end: all stage gates plus the Final Pass pass, producing the eight deliverable PNGs.

Related Skills