map-blockout 是一个用于 Unreal Engine 的程序化 FPS 开放世界地图灰盒(blockout)技能。它把 VibeUE 生成的地形(高度图 + 涂装层)转化为经过完整验证的 AAA 风格开放世界 FPS 地图布局,包含道路、POI、田地、森林/林线、铁路与桥梁,并可把规划物化为引擎中的真实几何。质量基准为 Arma / Squad。
用途与流程 该技能采用分阶段门禁式设计流程:每个阶段按 docs/design/map-designer-spec.md 中的权威规范执行有序的通过/失败检查,所有检查 PASS 之前不得进入下一阶段;失败时需修复问题元素并重新运行该阶段。推荐先加载 workflows.md 了解端到端运行方式(导出 → 阶段 1–5 → 最终检查 → 物化)。
主要能力
- Stage 0:调用 unreal.MapBlockoutService.export_landcover_grid(landscape_label, grid_n=120),一次原生调用读取源地形的所有涂装层与高度图,返回归一化网格,无需 PNG 往返或宿主 Python 预处理。
- 通过 run_full_pipeline 或便捷方法 run_full_pipeline_for_landscape 运行完整管线;后者在首次门禁失败时停止,并在返回结构体中给出失败检查项名称与消息。
- 四个逻辑涂装类别:crop、soil、flood(水)、forest。需通过 cfg.layers.crop / flood / forest / soil 将源地形上的层名映射到这些类别;flood 可为空,水会从高度图的低海拔百分位推导。
- 输出目录为 <Project>/Saved/MapBlockout/<level_name>/,必须交付 8 个文件:Stage1_Roads.png、Stage2_Roads_POIs.png、Stage3_Roads_POIs_Fields.png、Stage4_Roads_POIs_Fields_Foliage.png、Stage5_Roads_POIs_Fields_Foliage_Rail.png、CombinedFoliageAndMap.png、FoliageHeatMap.png、MapHeatMap.png。
- 颜色图例为权威标准(主路白、土路棕、林线浅紫、森林深紫、建筑浅灰、桥梁橙、铁路深灰、POI 边界亮绿圆圈、田地黄、灌木/矮林浅蓝),不得自创颜色;图例面板位于右上角,若与地图区域相交则该阶段“Color Key”检查失败。
使用方式 两阶段工作流。阶段 1(设计规划,CPU,掩码 + 折线,不生成引擎几何): 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: print(result.error_message) else: print("Wrote:", result.output_files)
阶段 2(物化到关卡): 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")
子文档 workflows.md:端到端运行;stage-rules.md:各阶段 CHECK 清单;config-reference.md:FMapBlockoutConfig 字段(覆盖带、道路网格、POI 目标、调参项);return-types.md:各服务方法返回的 USTRUCT 属性名;materialization.md:规划如何变成样条/涂装/Actor/植被。可通过引擎 AgentSkillToolset 的 GetSkills 请求 map-blockout/<section> 加载。
适用场景与限制 适用于为 FPS 开放世界地图生成灰盒布局并物化到 Unreal 关卡。状态为“完全实现”——每个阶段、最终检查、渲染器与物化器均已在 C++ 中上线,完整管线已验证端到端通过并产出 8 张 PNG。限制:门禁不可跳过;若存在未解决的失败,最终检查拒绝交付;若会话中存在 unreal-engine-skills-manager 外部 MCP 工具,可调用其加载 levels-and-world-partition 技能作为领域知识参考,否则跳过该行直接使用本技能。相关技能:landscape(先创建源地形)、terrain-data(真实世界高度图)、foliage(植被散布)。