# 关卡生成流水线

脚本集合会把 Excel 地图数据自动转成 Unity Prefab 与 C# 关卡字典，核心流程由 `run_pipeline.py` 串联。

## 环境准备
- Python 3.9 及以上（在 Windows PowerShell 5.1 上测试）
- Excel 源文件（默认 `global.xlsx`，需要遵循既定列结构）
- 依赖库：`pandas`、`openpyxl`

安装依赖：
```powershell
python -m pip install pandas openpyxl
```

## 快速上手
1. 将 Excel 文件（如 `global.xlsx`）放到仓库根目录下。
2. 确保模板 Prefab（默认 `Level90093.prefab`）可用。
3. 在 PowerShell 中运行：
   ```powershell
   python .\run_pipeline.py --excel global.xlsx --sheet Sheet2 --start-i 80316
   ```
   如果不传 `--steps`，脚本会顺序执行三个阶段（抽取数据 → 生成 C# → 生成 Prefab）。
   通过 `--steps 1,2` 可以只跑前两步。

### 输出文件
- `found_*.xlsx`：步骤 1 产出的坐标表（币 / p / v / 彩色格）
- `generated_levels.cs`：步骤 2 默认生成的关卡字典（可改名）
- `GeneratedPrefabs/LevelXXXX.prefab`：步骤 3 输出的 Prefab 文件

## 三个阶段
- **步骤 1（`read_excel.py`）**
  - 自动填补 Excel A 列的地图号（从 `--start-i` 指定的编号递增）。
  - 在 B~AA 列识别“币 / p / v”以及带方向的 `pN`、`vE` 等标记，输出 `found_币.xlsx`、`found_p.xlsx`、`found_v.xlsx`。
  - 解析单元格填充色：绿色写入 `found_方块.xlsx`，蓝/橙/粉分别写入 `found_water.xlsx`、`found_wall.xlsx`、`found_jump.xlsx`。
  - 如需核对颜色值，可使用 `inspect_cells.py` 指定单元格查看 ARGB 编码。

- **步骤 2（`write_code.py`）**
  - 读取步骤 1 的 Excel，按地图号聚合生成 `Spawn` 配置。
  - 默认输出到 `Levels90001.cs`，但 `run_pipeline.py` 会根据 `--output-levels` 参数覆盖（默认 `generated_levels.cs`）。
  - `LEVEL_PATH` 模板默认为 `Assets/Prefabs/Level/Level{map_id}.prefab`，如 Unity 资源路径调整需同步修改。

- **步骤 3（`make_prefab.py`）**
  - 以模板 Prefab 为基准，替换 `Ground` 与 `Border` 的 `m_Tiles` 数据。
  - 如果某图层无坐标，自动写入 `m_Tiles: {}` 以保持文件有效。
  - Ground 使用 0/0 索引；Border 根据 `found_water.xlsx`（0/0）、`found_wall.xlsx`（2/2）、`found_jump.xlsx`（1/1）写入不同 tile 索引，可按项目资源调整。

## 可调参数
- **`read_excel.py`**
  - `columns_to_preview`：控制调试日志预览列数。
  - `GREEN_COLORS` / `BLUE_COLORS` / `ORANGE_COLORS` / `PINK_COLORS`：定义可识别的填充色 ARGB 值。
  - `find_cells_with_currency_xlsx()` 的 `search_term` 及 `suffixes`：扩展新符号时调整。
  - `grid_columns` 默认覆盖 B~AA，如表头有改动需同步更新。
- **`write_code.py`**
  - `FILE_P` / `FILE_V` / `FILE_COIN`：输入文件名常量，可在运行前临时覆盖。
  - `LEVEL_PATH`、`boundary`、`direction_map`：匹配 Unity Prefab 路径与方向枚举时修改。
- **`make_prefab.py`**
  - 顶部 `EXCEL_PATH`、`TEMPLATE_PREFAB`、`OUTPUT_DIR`：控制输入表、模板与输出目录。
  - `OLD_LEVEL_NAME`：模板原始 Level 名称，替换节点名时会用到。
  - `TILE_LINE` 模板中的索引、`replace_tilemap_by_gameobject_name()` 查找的 GameObject 名称，如 Prefab 结构变更需同步更新。

> 如需适配新的 Excel 布局或颜色含义，请同时更新相关常量与字段映射。Prefab 模板层级或 Tilemap 名称变更时，也需更新 `make_prefab.py` 中的搜索关键字与 tile 索引分配。

## 常用命令行参数
- `--excel`：Excel 文件名
- `--sheet`：Sheet 名称
- `--start-i`：填补地图号的起始值
- `--template`：Prefab 模板路径
- `--steps`：指定执行的步骤（如 `1,3` 或 `all`）
- `--output-levels`：C# 输出文件名

## 辅助脚本
- `inspect_cells.py`：快速查看 Excel 指定单元格的填充色与字体信息。编辑脚本顶部的 `FILE`、`SHEET`、`CELLS` 后运行：
  ```powershell
  python .\inspect_cells.py
  ```
  输出会列出 ARGB 颜色码（`normalized` 字段）以及 openpyxl 能解析的原始索引，便于增补 `GREEN_COLORS` 等常量。

## 常见问题
- **缺少依赖**：重新执行安装命令。
- **Prefab 未生成**：确认 `found_方块.xlsx` 存在且列名与脚本一致，模板 Prefab 路径正确。
- **Tile 未正确替换**：检查模板中 `Ground`、`Border` 的 GameObject 名称以及 `m_Tiles` 结构是否被修改。

更多参数说明可执行：
```powershell
python .\run_pipeline.py --help
```