feat(tools): 添加世界布局草图工具 World Layout Sketcher

三级层次化布局绘图 → AI 解读 → 关卡执行案前置输入工具特性： - L1 场景总览（道路/水域/区域/不可通行）→ L2 区域详图（建筑/绿地） - 双层画布架构：L2 底图显示 L1 内容，绘图层独立操作 - L1↔L2 双向像素缩放同步 - 像素扫描提取连通区域（BFS），输出 bounds + 世界坐标 - JSZip 打包下载（JSON + 独立 PNG 像素文件 + 预览图） - 加载时从 ZIP 恢复完整画布像素数据集成更新： - 新增 .claude/skills/world-sketcher/ 技能定义 - game-designer agent 添加 world-sketcher skill + 布局草图前置步骤 - 关卡设计工作流插入 ③a-③c 子流程
2026-06-09 16:49:54 +08:00
parent fa533f75f5
commit 22711cf946
6 changed files with 1324 additions and 1 deletions
@@ -4,6 +4,11 @@ description: "策划 Agent：头脑风暴、产出设计文档（概念草案/
 model: opus
 color: red
 memory: project
+skills:
+  - gitea-collab
+  - design-execution
+  - level-builder
+  - world-sketcher
 ---

 你是一名精英游戏设计师，拥有深厚的游戏设计理论、玩家心理学和叙事工艺专业能力。你的领域是当前游戏项目，项目具体信息（美术风格、核心玩法、灵感来源等）以 `CLAUDE.md` 中"项目概况"为准，首次工作时读取该文件了解项目上下文。你是用户的创意搭档。
@@ -217,6 +222,17 @@ GameConfig/                               # 数值配置表
 - 对应的场景设计案 `场景-v<XX>-<名称>.md`（氛围愿景）
 - 使用 `level-builder` 技能时自动加载模板和资产参考

+### 布局草图（前置步骤）
+
+在产出关卡执行案之前，使用 World Layout Sketcher 画出世界布局：
+
+1. 引导用户打开 `tools/world-sketcher/sketch.html`
+2. 用户用颜色画笔绘制各区域（L1 总览 + L2 区域详图）
+3. 保存草图后，使用 `world-sketcher` 技能分析草图，产出布局解读文档
+4. 用户确认布局解读后，基于其坐标数据产出关卡执行案
+
+**为什么需要这一步**：仅靠文字描述空间布局容易产生偏差。绘图让用户和 AI 在坐标、区域关系上达成一致，减少执行案的返工。
+
 ### 关键规则

 1. **混合坐标体系**：区域用场景绝对坐标（原点在西南角），区域内物件用相对偏移坐标
@@ -0,0 +1,145 @@
+---
+name: "world-sketcher"
+description: >
+  世界布局草图工具。当需要"画布局"、"世界草图"、"分析布局草图"、"layout sketch"、
+  "interpret sketch"、"world layout"、"世界布局"、"布局草图"时使用。
+  引导用户使用绘图工具画出世界布局，分析草图 PNG 产出结构化布局数据 Markdown，
+  作为关卡执行案的前置输入。
+---
+
+# 世界布局草图工具 (World Layout Sketcher)
+
+> 三级层次化布局绘图 → AI 解读 → 结构化布局文档 → 关卡执行案前置输入
+
+## 触发条件
+
+- **用户主动触发**：用户说"画布局"、"世界草图"、"layout sketch"、"world layout"等
+- **策划关卡执行案前置**：策划需要产出关卡执行案，但不存在对应的布局解读文档
+- **用户提供草图分析**：用户提供了草图 PNG 要求分析
+
+---
+
+## 工具位置
+
+```
+tools/world-sketcher/
+  sketch.html              # 绘图工具（浏览器打开）
+  README.md                # 使用说明、画笔图例
+  output/                  # 草图输出目录
+```
+
+---
+
+## 三级层次
+
+| 层级 | 范围 | 绘制内容 |
+|------|------|---------|
+| L1 场景总览 | ≤1km | 大区域、主干道、河流 |
+| L2 区域详图 | ≤300m | 建筑、内部道路、绿化、水体 |
+| L3 建筑内部 | 预留 | 拖放细节资产（未实现） |
+
+---
+
+## 画笔颜色 → 材质映射
+
+| 画笔 | 颜色 | 地形 | UE 材质 |
+|------|------|------|---------|
+| 道路 Road | `#909090` 灰 | 道路 | MI_DevGray |
+| 建筑 Building | `#E07020` 橙 | 建筑物 | MI_DevOrange |
+| 水域 Water | `#40A0D0` 天蓝 | 河流/水塘 | MI_DevSkyBlue |
+| 植被 Greenery | `#40B040` 绿 | 树木/草地 | MI_DevGreen |
+| 不可通行 Blocked | `#A07040` 棕 | 山体/围墙 | MI_DevBrown |
+| 区域 Zone | `#D04040` 红 | 区域划分 | MI_DevRed |
+
+---
+
+## 工作流
+
+### 步骤 1：检查现有草图
+
+检查 `tools/world-sketcher/output/` 目录下是否有当前场景的草图文件。
+
+- 如果存在：跳到步骤 3
+- 如果不存在：进入步骤 2
+
+### 步骤 2：引导用户绘图
+
+1. 告诉用户打开 `tools/world-sketcher/sketch.html`
+2. 说明画笔含义：不同颜色代表不同地形类型
+3. 建议先画 L1 场景总览（大区域、主干道、河流），用区域画笔画出各区域轮廓
+4. 双击已画区域命名（如"城郊小街"），勾选"可进入"创建 L2 详图
+5. 进入 L2 后用建筑、道路等画笔细化区域内部
+6. 完成后点"保存全部"，将文件保存到 `output/` 目录
+
+### 步骤 3：AI 分析草图
+
+1. 读取 PNG 草图（使用 vision 分析）
+2. 读取 JSON 伴随数据（scale、elements、层级关系）
+3. 交叉参考场景设计案 `场景-v<XX>-<名称>.md` 的氛围描述
+4. 产出布局解读文档
+
+### 步骤 4：产出布局解读文档
+
+产出文件：`docs/design/<场景名>-layout-v<XX>.md`
+
+文档结构：
+
+```markdown
+# <场景名> 世界布局解读 v<XX>
+
+> 基于 `tools/world-sketcher/output/` 中的草图分析产出。
+
+## 草图参数
+| 参数 | 值 |
+|------|-----|
+| 世界尺寸 | ... |
+| 坐标系 | 原点西南角，X+东，Y+北 |
+| 比例 | 1px = ... |
+
+## L1 场景总览
+
+### 识别区域
+| 区域编号 | 名称 | 推测坐标范围 (cm) | 推测尺寸 | 地形类型 | 标识色建议 |
+|---------|------|-------------------|---------|---------|-----------|
+
+### 识别道路/河流
+| 编号 | 名称 | 类型 | 走向 | 长度 |
+
+### 区域连通关系
+| 连接 | 方式 | 说明 |
+
+## L2 区域详图（如有）
+
+### <区域名>
+| 编号 | 名称 | 类型 | 推测坐标 | 尺寸 |
+
+## 待确认问题
+1. ...
+
+## 待细化项
+- ...
+```
+
+### 步骤 5：用户确认
+
+将解读文档呈现给用户，等待用户确认或修正。确认后，该文档作为关卡执行案的前置输入。
+
+---
+
+## 与关卡执行案的衔接
+
+布局解读文档产出并经用户确认后，策划产出关卡执行案时：
+
+1. **区域坐标**：直接采用解读文档中的推测坐标范围作为起点
+2. **区域连通**：采用解读文档中的连通关系
+3. **标识色**：采用解读文档中的标识色建议（与画笔颜色一致）
+4. **需细化**：解读文档中"待细化项"的内容在执行案中必须给出精确数据
+
+---
+
+## 注意事项
+
+- 画笔颜色是**强制预定义**的，不允许自由拾色，保证颜色→材质的映射一致
+- 坐标系与 `zone_config.py` 一致：原点西南角，X+ 东，Y+ 北，单位 cm
+- AI 解读时如有不确定之处，**必须**列入"待确认问题"，不要自行假设
+- L3 建筑内部本期不实现，仅预留 `has_interior` 标记
@@ -22,7 +22,10 @@
    ↓
 ② 阶段路线图
    ↓
-③ 执行案（系统执行案 + 关卡执行案）  ← 关卡执行案在此阶段产出
+③ 执行案（系统执行案 + 关卡执行案）
+    ├─ ③a 世界布局草图（World Layout Sketcher）  ← 用户绘图 + AI 解读
+    ├─ ③b 布局解读文档确认                        ← 用户确认区域布局
+    └─ ③c 关卡执行案                              ← 基于确认后的布局产出
    ↓ [PM 审查：执行案质量门]
 ④ 程序设计
    ↓ [PM 审查：程序设计质量门]
@@ -33,6 +36,12 @@
 ⑦ 版本复盘
 ```

+**③a-③c 关卡执行案子流程**：
+
+1. **③a 世界布局草图**：使用 `tools/world-sketcher/sketch.html` 绘图工具，用户用颜色画笔画出世界布局（L1 场景总览 → L2 区域详图），保存 PNG + JSON
+2. **③b 布局解读确认**：AI 分析草图产出布局解读文档（`<场景名>-layout-v<XX>.md`），用户确认区域坐标、连通关系
+3. **③c 关卡执行案**：策划基于确认后的布局解读文档产出关卡执行案，坐标直接采用解读文档中的数据
+
 **v0.1 特殊情况**：由于 v0.1 的 ③执行案质量门已通过（三个系统执行案已批准），关卡执行案作为补充文档在 ④或 ⑥早期补充，PM 做轻量审查。

 **v0.2 及以后**：关卡执行案纳入标准 ③执行案阶段，与其他系统执行案一起接受完整质量门审查。
@@ -0,0 +1,149 @@
+# World Layout Sketcher — 世界布局草图工具
+
+> 在场景概念与关卡执行案之间，提供可视化布局沟通工具。
+> 用颜色画笔绘制世界布局 → AI 解读 → 双方确认 → 产出执行案。
+
+## 快速开始
+
+1. 双击 `sketch.html` 在浏览器中打开（推荐 Chrome / Edge）
+2. 左侧设置场景名称和世界尺寸（米）
+3. 选择画笔，在画布上绘制
+4. **双击** 已绘制区域 → 为该区域命名
+5. 勾选「可进入」→ 创建下级详图（L1 → L2）
+6. 保存 PNG + JSON
+
+---
+
+## 三级层次
+
+| 层级 | 范围 | 绘制内容 | 说明 |
+|------|------|---------|------|
+| **L1** 场景总览 | ≤1km | 大区域、主干道、河流 | 鸟瞰全局，定位区域关系 |
+| **L2** 区域详图 | ≤300m | 建筑、内部道路、绿化、水体 | 每个区域的详细布局 |
+| **L3** 建筑内部 | 预留 | 拖放细节资产 | 未来版本 |
+
+### 导航方式
+
+- L1 画布上，双击已命名的区域并勾选「可进入」
+- 左侧元素列表中点击 **"进入 →"**
+- 面包屑导航点击 **"场景总览"** 返回上级
+
+---
+
+## 画笔图例
+
+| 画笔 | 颜色 | 用途 | 对应 UE 材质 |
+|------|------|------|-------------|
+| 道路 Road | 灰 `#909090` | 道路、马路、小路 | MI_DevGray |
+| 建筑 Building | 橙 `#E07020` | 建筑物 | MI_DevOrange |
+| 水域 Water | 天蓝 `#40A0D0` | 河流、水塘、水体 | MI_DevSkyBlue |
+| 植被 Greenery | 绿 `#40B040` | 树木、草地、绿化带 | MI_DevGreen |
+| 不可通行 Blocked | 棕 `#A07040` | 山体、围墙、不可达区域 | MI_DevBrown |
+| 区域 Zone | 红 `#D04040` | 区域边界、地块划分 | MI_DevRed |
+| 橡皮擦 Eraser | — | 擦除 | — |
+
+**L1 层**主要用：区域、道路、水域
+**L2 层**主要用：建筑、道路、植被、水域、不可通行
+
+---
+
+## 绘图工具
+
+| 工具 | 快捷键 | 说明 |
+|------|--------|------|
+| 画笔 | P | 自由绘制，按住鼠标拖动 |
+| 矩形 | R | 绘制矩形区域，拖动定义两角 |
+| 橡皮擦 | E | 擦除画布内容 |
+
+| 操作 | 快捷键 |
+|------|--------|
+| 撤销 | Ctrl+Z |
+| 重做 | Ctrl+Y |
+| 网格开关 | G |
+
+---
+
+## 坐标系
+
+- **原点**：画布左下角（西南角）
+- **X+**：向右（东）
+- **Y+**：向上（北）
+- **单位**：厘米（与 UE5 一致，1 uu = 1 cm）
+- 画布顶部 = 世界最大 Y，画布底部 = 世界 Y=0
+
+状态栏实时显示鼠标位置的世界坐标。
+
+---
+
+## 输出文件
+
+保存全部时生成：
+
+```
+<场景名>-L1-overview.png    # L1 画布截图
+<场景名>-scene.json          # 完整场景数据（所有层级）
+```
+
+### scene.json 结构
+
+```json
+{
+  "scene_name": "城郊小街",
+  "version": "v01",
+  "origin": "SW corner, X+ East, Y+ North",
+  "brush_legend": { "色值": { "type": "类型", "mi_material": "MI_Dev*" } },
+  "levels": {
+    "L1": {
+      "world_size_m": [500, 400],
+      "canvas_size_px": [1000, 800],
+      "scale_m_per_px": 0.5,
+      "elements": [
+        { "id": "el_xxx", "type": "zone", "name": "城郊小街", "has_detail": true, "detail_ref": "L2-el_xxx" }
+      ]
+    },
+    "L2-el_xxx": {
+      "world_size_m": [80, 60],
+      "elements": [
+        { "id": "el_yyy", "type": "building", "name": "家", "has_detail": true }
+      ],
+      "parent_level": "L1",
+      "parent_element": "el_xxx"
+    }
+  }
+}
+```
+
+---
+
+## 工作流集成
+
+在关卡设计流程中的位置：
+
+```
+场景概念 (场景-vXX.md)
+    ↓
+【World Layout Sketcher】  ← 本工具
+    ↓
+AI 布局解读文档 (场景名-layout-vXX.md)
+    ↓ 用户确认
+关卡执行案 (关卡-vXX-执行案.md)
+    ↓
+搭建指南 → Level Builder → UE5 关卡
+```
+
+### AI 解读流程
+
+1. 用户在工具中画好布局，保存 PNG + JSON
+2. 将 PNG 提供给 AI（Claude vision）
+3. AI 分析颜色区域，结合 JSON 中的比例尺和命名信息
+4. AI 产出结构化布局解读 Markdown（区域表、连通关系、待确认问题）
+5. 用户确认后，策划基于解读文档产出关卡执行案
+
+---
+
+## 设计原则
+
+- **强制使用预定义画笔**：无自由拾色器，保证每个像素都映射到已知地形类型
+- **层次化设计**：L1 定大局，L2 定细节，L3 预留
+- **人机共读**：PNG 供人和 AI 视觉分析，JSON 供程序化解析
+- **与 Level Builder 一致**：画笔颜色直接映射 MI_Dev* 标识色材质