# World Layout Sketcher — 世界布局草图工具

> 在场景概念与关卡执行案之间，提供可视化布局沟通工具。
> 用颜色画笔绘制世界布局 → AI 解读 → 双方确认 → 产出执行案。

---

## 快速开始

### 方式一：本地服务器（推荐）

保存/加载直接读写 `output/` 目录，无需手动下载。

1. 双击 `start.bat`
2. 浏览器自动打开 `http://localhost:8765/sketch.html`
3. 开始绘制，点"保存"直接存入 `output/`

> 需要 Python 3。关闭终端窗口即可停止服务器。

### 方式二：直接打开 HTML

双击 `sketch.html` 在浏览器中打开（推荐 Chrome / Edge）。

- 保存时通过浏览器下载 ZIP 文件
- 加载时通过浏览器文件选择器选择 ZIP

> **注意**：直接打开 HTML 时加载独立的 `.json` 文件**不会恢复画布位图**——位图数据存储在 ZIP 包内的 PNG 文件中，必须加载 `.zip` 文件才能完整恢复。

---

## 文件结构

```
world-sketcher/
├── start.bat           ← 启动脚本（双击运行）
├── server.py           ← 本地保存/加载服务器
├── sketch.html         ← 主工具（单文件，浏览器运行）
├── README.md
└── output/             ← 保存/加载目录
    ├── 迈皋桥-scene.zip     ← 完整场景包（JSON + 所有 PNG）
    ├── 迈皋桥-scene.json    ← 结构化数据（不含位图）
    ├── 迈皋桥-L1-drawing.png       # L1 画布像素数据
    ├── 迈皋桥-L1-overview-preview.png  # L1 合并预览
    └── 迈皋桥-L2-*-drawing.png      # L2 各区域画布数据
```

---

## 基本操作

1. 左侧设置**场景名称**和**世界尺寸**（米）
2. 选择画笔，在画布上绘制
3. **双击** 已绘制区域 → 弹出命名对话框：
   - 输入名称（如"家"、"小卖部"）
   - **L1 区域**：设置**地形标高**（米，可为负值表示洼地）
   - **L2 建筑**：设置**建筑高度**（米）
   - 勾选**连通到**其他已命名区域（建立连接关系）
   - 勾选「可进入」→ 创建下级详图（L1 → L2）
4. 保存 → 存入 `output/`（服务器模式）或浏览器下载（离线模式）

### 画布标签

- **L1 层**：显示区域名称 + 地形标高（如 `棚户区 (标高2m)`）
- **L2 层**：显示建筑名称 + 建筑高度（如 `棚户1 (3m)`）
- 标高为 0 时不显示高度

---

## 三级层次

| 层级 | 范围 | 绘制内容 | 说明 |
|------|------|---------|------|
| **L1** 场景总览 | ≤1km | 大区域、主干道、河流 | 鸟瞰全局，定位区域关系 |
| **L2** 区域详图 | ≤300m | 建筑、内部道路、绿化、水体 | 每个区域的详细布局 |
| **L3** 建筑内部 | 预留 | 拖放细节资产 | 未来版本 |

### 导航方式

- L1 画布上，双击已命名的区域并勾选「可进入」
- 左侧元素列表中点击 **"进入 →"**
- 面包屑导航点击 **"场景总览"** 返回上级
- 返回 L1 时，L2 的绘制内容会自动合成回 L1 对应区域

---

## 画笔图例

| 画笔 | 颜色 | 用途 | 对应 UE 材质 | 可用层级 | 高度含义 |
|------|------|------|-------------|---------|---------|
| 道路 Road | 灰 `#909090` | 道路、马路、小路 | MI_DevGray | L1/L2 | — |
| 建筑 Building | 橙 `#E07020` | 建筑物 | MI_DevOrange | L2 | 建筑高度 |
| 水域 Water | 天蓝 `#40A0D0` | 河流、水塘、水体 | MI_DevSkyBlue | L1/L2 | — |
| 植被 Greenery | 绿 `#40B040` | 树木、草地、绿化带 | MI_DevGreen | L2 | 2m |
| 不可通行 Blocked | 棕 `#A07040` | 山体、围墙、不可达区域 | MI_DevBrown | L1/L2 | 3m |
| 区域 Zone | 红 `#D04040` | 区域边界、地块划分 | MI_DevRed | L1 | 地形标高 |
| 橡皮擦 Eraser | — | 擦除 | — | L1/L2 | — |

---

## 快捷键

| 操作 | 快捷键 |
|------|--------|
| 画笔工具 | P |
| 橡皮擦工具 | E |
| 撤销 | Ctrl+Z |
| 重做 | Ctrl+Y |
| 网格开关 | G |

---

## 坐标系

- **原点**：画布左下角（西南角）
- **X+**：向右（东）
- **Y+**：向上（北）
- **单位**：厘米（与 UE5 一致，1 uu = 1 cm）
- 画布顶部 = 世界最大 Y，画布底部 = 世界 Y=0

状态栏实时显示鼠标位置的像素坐标和世界坐标。

---

## 输出格式

### scene.json 结构

```json
{
  "scene_name": "迈皋桥",
  "version": "v02",
  "created": "2026-06-09T16:46:32",
  "origin": "SW corner, X+ East, Y+ North",
  "brush_legend": {
    "#D04040": { "type": "zone", "label": "区域 Zone", "mi_material": "MI_DevRed" }
  },
  "levels": {
    "L1": {
      "world_size_m": [500, 400],
      "canvas_size_px": [1000, 800],
      "scale_m_per_px": 0.5,
      "elements": [
        {
          "id": "el_001", "type": "zone", "name": "棚户区",
          "height_m": 2, "connections": ["el_002"],
          "has_detail": true, "detail_ref": "L2-el_001"
        }
      ],
      "regions": [
        {
          "id": "r_001", "type": "zone", "name": "棚户区",
          "bounds_world_m": [5.0, 5.0, 120.0, 95.0],
          "area_px": 15000
        }
      ],
      "image_file": "迈皋桥-L1-drawing.png",
      "l1_base_file": null
    },
    "L2-el_001": {
      "world_size_m": [80, 60],
      "elements": [
        { "id": "el_010", "type": "building", "name": "棚户1", "height_m": 3 }
      ],
      "image_file": "迈皋桥-L2-el_001-drawing.png",
      "l1_base_file": "迈皋桥-L2-el_001-l1base.png",
      "parent_level": "L1",
      "parent_element": "el_001"
    }
  }
}
```

### 高度字段语义

| 层级 | 元素类型 | `height_m` 含义 | 用途 |
|------|---------|----------------|------|
| L1 | zone（区域） | **地形标高** | 地面海拔相对高度，0=基准面，负值=洼地 |
| L2 | building（建筑） | **建筑高度** | 建筑物垂直高度 |
| L1/L2 | blocked（不可通行） | **障碍高度** | 围墙/山体等垂直尺度 |

---

## 本地服务器

`server.py` 提供三个 HTTP 端点，供 `sketch.html` 直接读写 `output/` 目录：

| 端点 | 方法 | 说明 |
|------|------|------|
| `/list` | GET | 列出 `output/` 下所有 `.json` / `.zip` 文件 |
| `/load/<filename>` | GET | 从 `output/` 读取指定文件 |
| `/save` | POST (multipart) | 接收文件并保存到 `output/` |

服务器运行时，sketch.html 自动检测并使用服务器模式；未运行时自动回退到浏览器下载/文件选择。

手动启动：
```bash
python server.py          # 默认端口 8765
python server.py 9000     # 自定义端口
```

---

## 工作流集成

在关卡设计流程中的位置：

```
场景概念 (场景-vXX.md)
    ↓
【World Layout Sketcher】  ← 本工具
    ↓
AI 布局解读文档 (场景名-layout-vXX.md)
    ↓ 用户确认
关卡执行案 (关卡-vXX-执行案.md)
    ↓
搭建指南 → Level Builder → UE5 关卡
```

### AI 解读流程

1. 用户在工具中画好布局，命名区域，设置标高/高度和连通关系，保存
2. AI 读取 JSON 中的 elements + regions + connections + height_m
3. AI 交叉参考场景设计案的氛围描述，将 JSON 数据与场景概念建立映射
4. AI 产出结构化布局解读 Markdown（区域表、连通关系、标高、待确认问题）
5. 用户确认后，策划基于解读文档产出关卡执行案

> PNG 文件用于画布的保存/加载和人工预览。AI 分析以 JSON 结构化数据为准，不依赖 PNG 像素分析。

---

## 设计原则

- **预定义画笔**：无自由拾色器，保证每个像素都映射到已知地形类型
- **结构化数据优先**：标高、高度和连通关系由用户直接输入，AI 无需从图像推断
- **层次化设计**：L1 定大局，L2 定细节，L3 预留
- **人机共读**：PNG 供人视觉确认，JSON 供 AI 和程序化解析
- **材质一致**：画笔颜色直接映射 UE5 的 MI_Dev* 标识色材质
- **离线优先**：单 HTML 文件即可使用，服务器仅为便利增强