diff --git a/.claude/agents/game-designer.md b/.claude/agents/game-designer.md index 4face5a..2adebff 100644 --- a/.claude/agents/game-designer.md +++ b/.claude/agents/game-designer.md @@ -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-<名称>.md`（氛围愿景） - 使用 `level-builder` 技能时自动加载模板和资产参考 +### 布局草图（前置步骤） + +在产出关卡执行案之前，使用 World Layout Sketcher 画出世界布局： + +1. 引导用户打开 `tools/world-sketcher/sketch.html` +2. 用户用颜色画笔绘制各区域（L1 总览 + L2 区域详图） +3. 保存草图后，使用 `world-sketcher` 技能分析草图，产出布局解读文档 +4. 用户确认布局解读后，基于其坐标数据产出关卡执行案 + +**为什么需要这一步**：仅靠文字描述空间布局容易产生偏差。绘图让用户和 AI 在坐标、区域关系上达成一致，减少执行案的返工。 + ### 关键规则 1. **混合坐标体系**：区域用场景绝对坐标（原点在西南角），区域内物件用相对偏移坐标 diff --git a/.claude/skills/world-sketcher/SKILL.md b/.claude/skills/world-sketcher/SKILL.md new file mode 100644 index 0000000..c14c2cd --- /dev/null +++ b/.claude/skills/world-sketcher/SKILL.md @@ -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-<名称>.md` 的氛围描述 +4. 产出布局解读文档 + +### 步骤 4：产出布局解读文档 + +产出文件：`docs/design/<场景名>-layout-v.md` + +文档结构： + +```markdown +# <场景名> 世界布局解读 v + +> 基于 `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` 标记 diff --git a/docs/design/关卡设计工作流.md b/docs/design/关卡设计工作流.md index b977a79..14c8a77 100644 --- a/docs/design/关卡设计工作流.md +++ b/docs/design/关卡设计工作流.md @@ -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.md`），用户确认区域坐标、连通关系 +3. **③c 关卡执行案**：策划基于确认后的布局解读文档产出关卡执行案，坐标直接采用解读文档中的数据 + **v0.1 特殊情况**：由于 v0.1 的 ③执行案质量门已通过（三个系统执行案已批准），关卡执行案作为补充文档在 ④或 ⑥早期补充，PM 做轻量审查。 **v0.2 及以后**：关卡执行案纳入标准 ③执行案阶段，与其他系统执行案一起接受完整质量门审查。 diff --git a/tools/world-sketcher/README.md b/tools/world-sketcher/README.md new file mode 100644 index 0000000..f7da0c1 --- /dev/null +++ b/tools/world-sketcher/README.md @@ -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* 标识色材质 diff --git a/tools/world-sketcher/output/.gitkeep b/tools/world-sketcher/output/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tools/world-sketcher/sketch.html b/tools/world-sketcher/sketch.html new file mode 100644 index 0000000..4402b31 --- /dev/null +++ b/tools/world-sketcher/sketch.html @@ -0,0 +1,1004 @@ + + + + + +ChildHood — World Layout Sketcher + + + + +
+ +
+
+
+ + +
+
+ + +
+
+ +
+
+ + +
+
+
+
+ + + + +
+
+
+ -- + L1 场景总览 + 1000 × 800 + +
+
+
+ +
+
+

命名元素

+ + +
+ + +
+
+
+ + + + + +