ChildHood/tools/world-sketcher/README.md

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 结构

{
  "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* 标识色材质