# execution-to-guide

关卡执行案 → 搭建指南 转换器。

将 `docs/design/关卡-vXX-<名称>-执行案.md` 自动转换为 `docs/technical/关卡-vXX-搭建指南.md`，供 `level-builder` 工具解析并在 UE5 中搭建白模关卡。

## 用法

```bash
# 基本用法（自动推断输出路径到 docs/technical/）
cd tools/execution-to-guide
python converter.py -i ../../docs/design/关卡-v01-城郊小街-执行案.md

# 指定输出路径
python converter.py -i ../../docs/design/关卡-v01-城郊小街-执行案.md -o ../../docs/technical/关卡-v01-搭建指南.md

# 详细日志
python converter.py -i <执行案.md> -v
```

## 依赖

- `tools/level-builder/config/` 下的 `asset_mapping.py`、`material_mapping.py`、`substitution_rules.py`
- `tools/level-builder/parsers/markdown_table.py`

工具会自动从上级 `level-builder` 目录加载这些依赖。

## 模块说明

| 文件 | 功能 |
|------|------|
| `converter.py` | 主入口，编排解析→展开→生成流程 |
| `execution_parser.py` | 解析执行案 Markdown，提取区域/结构体/布景/组合资产/边界/光照 |
| `asset_expander.py` | 将 BSP 资产建议字符串展开为 Actor 规格（坐标计算、旋转推断、资产映射） |
| `guide_writer.py` | 生成搭建指南 Markdown（匹配 `build_guide_parser.py` 的格式预期） |
| `composite_writer.py` | 生成组合资产清单 + JSON 模板（无直接 BSP 匹配的物件） |

## 数据流

```
关卡执行案 (.md)
      │
      ▼
execution_parser.py → ExecutionPlanData
      │
      ▼
asset_expander.py → list[ActorSpec]   (展开 BSP 建议 + 坐标计算)
      │
      ▼
guide_writer.py → 搭建指南 (.md)      (精确匹配 build_guide_parser 格式)
composite_writer.py → 组合资产清单 (.md + .json)
```