starmen1265/ChildHood
1
0
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects 2 Releases Wiki Activity

feat(tools): 白模关卡自动生成Python脚本——Level Builder

Browse Source 
两阶段流水线：搭建指南Markdown → JSON → UE5 Actor
- 解析器：4种表格变体+范围展开+坐标表达式计算
- 配置：37种BSP资产映射+13种材质+7区域定义
- 验证：265个Actor全部通过，0错误
- Builder：UE5 Python API自动放置Actor+材质+Outliner
- 报告：自动生成搭建报告Markdown

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
starmen1265
2026-06-07 23:03:45 +08:00
parent 8011cb6472
commit 0f96b79dba
74 changed files with 10468 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/refs/development-workflow.md
+24 -24
View File
@@ -66,7 +66,7 @@
#### 产出
**玩法草案文档**（`docs/design/concept.md`），包含以下 7 个字段：
**玩法草案文档**（`docs/design/概念草案.md`），包含以下 7 个字段：
1. **一句话描述** — 用一句话说清楚这是什么游戏
2. **玩家核心游玩内容与感受** — 玩家在游戏中的核心操作和活动，以及游戏希望带给玩家的情感基调、视觉风格和整体感受
@@ -76,7 +76,7 @@
6. **市场定位与三大卖点** — 游戏在市场中的定位（品类、平台、价位），以及最能吸引玩家的三个核心卖点
7. **参考** — 灵感来源（其他游戏、电影、书、某种经历）
**美术风格指南**（`docs/art/style-guide.md`）— 确定视觉方向。
**美术风格指南**（`docs/art/美术风格指南.md`）— 确定视觉方向。
**技术可行性评估** — 评估核心玩法在目标引擎/平台上的实现可行性。
@@ -107,7 +107,7 @@
| 层级 | 定位 | 比喻 | 特点 |
|------|------|------|------|
| **草案** (concept.md) | 给游戏**定调** | 灵魂 | 回答"这个游戏是什么"，简略但方向明确 |
| **草案** (概念草案.md) | 给游戏**定调** | 灵魂 | 回答"这个游戏是什么"，简略但方向明确 |
| **设计案** | 给游戏**定骨架** | 骨架 | 基于草案的原则展开系统设计，定义有哪些系统、系统关系、核心行为 |
| **执行案** | 给游戏**填血肉** | 血肉 | 细化到程序可直接实现的交互规则和行为细节 |
@@ -123,7 +123,7 @@
#### 阶段路线图
原型阶段开始时，产出**阶段路线图**（`docs/plans/prototype-roadmap.md`）：
原型阶段开始时，产出**阶段路线图**（`docs/plans/原型阶段-路线图.md`）：
- 计划分几个版本迭代
- 每个版本探索哪个方向（验证什么假设）
@@ -149,10 +149,10 @@
```
docs/design/prototype/
player-controller.md # 设计案
player-controller-execution.md # 执行案（含迭代版本表头）
interaction-system.md
interaction-system-execution.md
玩家控制器.md # 设计案
玩家控制器-执行案.md # 执行案（含迭代版本表头）
交互系统.md
交互系统-执行案.md
...
```
@@ -195,7 +195,7 @@ docs/design/prototype/
#### 阶段路线图
批量生产阶段开始时，产出**阶段路线图**（`docs/plans/production-roadmap.md`）：
批量生产阶段开始时，产出**阶段路线图**（`docs/plans/批量生产阶段-路线图.md`）：
- 计划分几个版本迭代
- 每个版本的主要内容范围
@@ -212,8 +212,8 @@ docs/design/prototype/
```
docs/design/production/
player-controller.md # 在原型基础上更新
player-controller-execution.md # 继续迭代，追加新的迭代记录
玩家控制器.md # 在原型基础上更新
玩家控制器-执行案.md # 继续迭代，追加新的迭代记录
...
```
@@ -357,7 +357,7 @@ docs/design/production/
6. **版本间的递进关系**：为什么先做这些后做那些
7. **每个版本的验收标准**：怎样算"这个版本做完了"
**产出位置**：`docs/plans/prototype-roadmap.md` 或 `docs/plans/production-roadmap.md`
**产出位置**：`docs/plans/原型阶段-路线图.md` 或 `docs/plans/批量生产阶段-路线图.md`
**版本编号规则**：
- 原型阶段：`v0.1`、`v0.2`、`v0.3`……
@@ -432,16 +432,16 @@ docs/design/production/
**产出形式**：
- 每个系统一份执行案，放在 `docs/design/<阶段>/` 目录下
- 文件命名：`<系统名>-execution.md`（如 `player-controller-execution.md`）
- 文件命名：`<系统名>-执行案.md`（如 `玩家控制器-执行案.md`）
- 不按版本分文件，通过迭代记录表头追踪变更
- **关卡执行案**（如有场景搭建需求）：文件命名 `level-v<XX>-<name>-execution.md`，产出模板参见 `.claude/refs/level-execution-template.md`
- **关卡执行案**（如有场景搭建需求）：文件命名 `关卡-v<XX>-<名称>-执行案.md`，产出模板参见 `.claude/refs/关卡执行案模板.md`
**关卡执行案**：
- 当版本开发涉及场景搭建时，策划额外产出一份关卡执行案
- 关卡执行案将场景设计案的氛围描述转化为空间精度搭建指南（坐标、尺寸、BSP 资产映射）
- 使用混合坐标体系：区域用场景绝对坐标，区域内物件用相对偏移坐标
- 交互物和收集品的位置标注必须与交互系统/收集系统执行案交叉引用
- 完整规范参见 `docs/design/prototype/level-design-workflow.md`
- 完整规范参见 `docs/design/prototype/关卡设计工作流.md`
---
@@ -468,7 +468,7 @@ docs/design/production/
- **不通过** → 退回策划修改，列出具体问题清单
- **争议** → PM 与策划对判定有分歧时，由用户最终裁决
**产出**：PM 审查记录（记录在 `docs/plans/reviews/<任务ID>-review.md`）
**产出**：PM 审查记录（记录在 `docs/plans/reviews/<任务ID>-审查记录.md`）
---
@@ -495,7 +495,7 @@ docs/design/production/
| 数据流 | 允许硬编码 | 数据应配置化 |
| 美术需求 | 允许简化描述 | 必须具体到尺寸和数量 |
**产出位置**：`docs/technical/<系统名>-tech.md`
**产出位置**：`docs/technical/<系统名>-技术方案.md`
---
@@ -534,7 +534,7 @@ docs/design/production/
**产出位置**：
- 资产放 `Content/` 对应目录
- 清单记录在 `docs/art/asset-manifest.md` 或直接在技术方案中更新
- 清单记录在 `docs/art/资产清单.md` 或直接在技术方案中更新
---
@@ -564,13 +564,13 @@ docs/design/production/
**白模搭建子任务（6a）**：
当版本开发涉及场景搭建时，⑥的第一个子任务是白模关卡搭建：
- 读取关卡执行案 `level-v<XX>-<name>-execution.md` 和场景设计案
- 读取关卡执行案 `关卡-v<XX>-<名称>-执行案.md` 和场景设计案
- 使用 `Content/BlockingStarterPack/` 资产在 UE5 编辑器中搭建白模关卡
- 按区域分文件夹组织 Actor（命名规范：`LVL_<ZoneID>_<Category>_<Description>`）
- 完成比例验证（角色可通过门洞、摄像机不穿墙、流线通行）
- 产出搭建报告 `docs/technical/level-v<XX>-build-report.md` 记录偏差
- 产出搭建报告 `docs/technical/关卡-v<XX>-搭建报告.md` 记录偏差
- **搭建报告必须以评论形式发布到对应任务 Issue**（与本地文件内容一致）
- 完整搭建流程参见 `docs/design/prototype/level-design-workflow.md` 第四章
- 完整搭建流程参见 `docs/design/prototype/关卡设计工作流.md` 第四章
**阶段差异**：
@@ -611,7 +611,7 @@ docs/design/production/
- **不通过（重大）** → PM 提出处理建议（回退步骤或开新版本），由用户最终决定
- **争议** → PM 与程序对判定有分歧时，由用户最终裁决
**产出**：PM 审查记录（记录在 `docs/plans/reviews/<任务ID>-review.md`）
**产出**：PM 审查记录（记录在 `docs/plans/reviews/<任务ID>-审查记录.md`）
---
@@ -656,14 +656,14 @@ PM 在每次 `/plan` 调用时，先判断宏观阶段，再针对**当前版本
| 检查项 | 判断方式 | 结果 |
|--------|----------|------|
| 项目处于哪个开发阶段？ | 检查 `concept.md` → 检查核心玩法是否已有可玩原型 → 检查内容是否已完整 | 草案 / 原型 / 批量生产 / 测试发布 |
| 项目处于哪个开发阶段？ | 检查 `概念草案.md` → 检查核心玩法是否已有可玩原型 → 检查内容是否已完整 | 草案 / 原型 / 批量生产 / 测试发布 |
### 版本流水线检查
| 检查项 | 检查方式 | 通过条件 |
|--------|----------|----------|
| ① 设计案是否存在且完整？ | 检查 `docs/design/<阶段>/` 中的设计文档和索引 | 覆盖所有主要系统，有索引串联 |
| ② 阶段路线图是否存在？ | 检查 `docs/plans/<阶段>-roadmap.md` | 版本列表、每版本目标、递进关系明确 |
| ② 阶段路线图是否存在？ | 检查 `docs/plans/<阶段>-路线图.md` | 版本列表、每版本目标、递进关系明确 |
| ③ 执行案是否齐全？ | 检查 `docs/design/<阶段>/` 对应执行案 | 每个涉及系统的核心行为规则都已明确 |
| **PM 审查**：执行案质量门 | 对照质量标准逐项检查 | 完整性、清晰性、边界情况通过 |
| ④ 程序设计方案是否齐全？ | 检查 `docs/technical/` 对应文档 | 每个执行案都有对应技术方案 |