# S-26 · 0.4.0「城市风格原型」说明

> 单个 HTML 文件、双击即开、离线可跑、零外链。三套城市风格（A 清爽卡通 / B 细节派 / C 霓虹夜景）共用同一座六边形小岛、同一套布局与街道道具，**一键切换只换皮**，方便你在同一机位直接对比。

- demo：`tasks-out/S-26/demo/city-0.4.0.html`（600 KiB，gzip 160 KiB，内联 three.js）
- 证据图：`tasks-out/S-26/evidence/`（3 风格 × 4 机位 = 12 张 + 三风格并排对比 1 张 + 4 张 HUD 预览）
- 自检：`tasks-out/S-26/evidence/selfcheck.md`（typecheck / 单测 11 项 / 60 s 车流仿真 / 真浏览器交互相 28 项 / 基线 sha256）

---

## 1. 怎么玩

双击 `city-0.4.0.html`（Chrome / Edge / Safari 均可，`file://` 直接跑，不联网）。

| 操作 | 效果 |
| --- | --- |
| 鼠标左键拖拽 / 单指滑 | 水平 360° 旋转 + 俯仰（限位 12°~88°，不会翻到岛下面） |
| 滚轮 / 双指捏合 | 缩放（限位 15~72，拉太近会自动抬到最高塔之上，相机不会钻进塔楼/岛体） |
| 左上角面板 | **实时 FPS / 三角形 / draw call** + 当前风格、日/夜、车/人数量 |
| 底部按钮 | A/B/C 风格、日间/夜间、车流开/关、行人开/关、重置视角 |

切风格、切昼夜**保持当前机位不变**，方便在同角度对比。

URL 参数（截图/调试用）：`?style=B&night=1&cam=close&cars=30&peds=60&nohud=1`
（`cam` 取 `default / top / close / wide`）。

---

## 2. 三套风格

### A 清爽卡通 · 厚块面 + 双色墙 + 暖窗

![A 默认机位](evidence/styleA-default.png)
![A 近景](evidence/styleA-close.png)
![A 俯视](evidence/styleA-top.png)

**一句话差异**：最「低多边形卡通」的一套——厚块面、暖黄/珊瑚双色墙环、每层奶油腰线、大颗暖窗、红四坡屋顶 + 屋顶水箱/空调/天线，白天最讨喜、饱和度最高。
（夜景：`evidence/styleA-night.png`）

### B 细节派 · 竖窗格 + 阳台 + 空调外机 + 天线

![B 默认机位](evidence/styleB-default.png)
![B 近景](evidence/styleB-close.png)
![B 俯视](evidence/styleB-top.png)

**一句话差异**：装饰密度最高——每面 4~6 条竖向窄窗 + 壁柱、每 2~3 层外挑阳台带栏杆、每层 2~3 台空调外机、入口斜雨棚、屋顶机组/双水箱/多段天线，冷灰蓝调、最「写实」。
（夜景：`evidence/styleB-night.png`）

### C 霓虹夜景 · 玻璃幕墙 + 发光条带 + 霓虹招牌

![C 默认机位](evidence/styleC-default.png)
![C 近景](evidence/styleC-close.png)
![C 俯视](evidence/styleC-top.png)

**一句话差异**：夜色主角——幕墙分格玻璃（明度做「天空反射渐变」）、每层/隔层发光条带、四角竖向霓虹、楼顶招牌、商场大 LED 屏、地标塔冠发光环，夜里整面楼会亮起来；白天是冷调玻璃塔。
（夜景：`evidence/styleC-night.png`）

### 三风格并排（同一机位、同一张图）

![三风格并排](evidence/compare-styles.png)

---

## 3. 性能

**几何预算**（单套风格实际提交给 GPU 的三角形，含阴影 pass 前后对照）：

| 组件 | 几何三角形 | 网格 / draw call | 说明 |
| --- | --- | --- | --- |
| 六边形岛（地形 + 水面） | 1,256 | 2 | 草顶/草唇/表土/深土/砂/岩 4 层剖面 + 3 街 + 人行道 + 标线 + 海面 |
| 天空穹顶 | 720 | 1 | 顶点色渐变 + 程序化星星，无贴图 |
| 塔楼 风格 A | 7,956 | 2 | 1 不透明合并网格 + 1 发光合并网格 |
| 塔楼 风格 B | 11,204 | 2 | 同上 |
| 塔楼 风格 C | 8,200 | 2 | 同上 |
| 街道道具（三风格同布局） | 11,396 | 2 | 路灯/长椅/树池/斑马线/广告牌/霓虹牌/天桥/码头 |
| 车流 + 行人 | 984 | 6 | 3 车型 + 3 行人 InstancedMesh（18 车 / 36 人） |
| **合计（A / B / C）** | **22,312 / 25,560 / 22,556** | **13** | 加阴影 pass 后整帧 draw call **18** |

**截图实测（1440×900，SwiftShader 软件渲染）**：

| 风格 | 三角形 | draw call | FPS 范围（软渲染） |
| --- | --- | --- | --- |
| A 清爽卡通 | 45,516 | 18 | 10.7 ~ 19.4 |
| B 细节派 | 56,012 | 18 | 8.5 ~ 22.3 |
| C 霓虹夜景 | 43,604 | 18 | 10.0 ~ 35.4 |

- 预算：**draw call ≤ 70**（实测 18，26%）、**三角形 ≤ 150k**（实测峰值 56,012，37%）——都在预算内。
- 注意：截图里的三角形 ≈ 几何量 × 2，因为 `renderer.info` 把**阴影 pass** 也算进去了。
- **FPS 必须如实说明**：本机无 GPU，Chromium 走 SwiftShader 软件渲染，这一列**不代表真机帧率**。三角形 / draw call 与硬件无关，是可验收的指标；真机（桌面独显/核显）预期 60 fps，移动端建议 0.4.1 集成时再实测一次并据实标注。
- 阴影：PCF 2048，仅塔楼/道具/车辆投影（发光网格不投影，行人也不投影，省 3 个 shadow draw call）。

---

## 4. 请你拍板的 5 个问题（各选一个，回复形如 `1A 2B 3A 4B 5A` 即可）

**Q1. 0.4.1 集成进游戏时，主风格用哪套？**
- A）清爽卡通（A）——最贴合「卡通低多边形城市」基调，远看最清楚
- B）细节派（B）——近看最有内容，适合镜头会拉近的玩法
- C）霓虹夜景（C）——夜戏/赛博感最强，但白天偏冷

**Q2. 夜间整体亮度（关系到「晚上能不能看清路和车」）？**
- A）现在这样（含蓄，靠窗光/路灯照地）——夜景氛围最浓
- B）再亮一档（整体抬环境光，能看清全岛轮廓）
- C）分风格定（A/B 亮、C 保持很暗）

**Q3. 四栋楼的体量差异（现在是 tier1 商场 4 层 / tier2 住宅 8 层 / tier3 写字楼 12 层 / tier4 地标 17 层）？**
- A）保持（差距明显，一眼能看出层级）
- B）拉大（地标更高、矮楼更矮，层级更夸张）
- C）缩小（城市天际线更平，强调「一片街区」而不是「四根柱子」）

**Q4. 街道道具密度（现在约 22 盏路灯 / 18 个树池 / 4 张长椅 / 3 块广告牌 / 3 个霓虹牌 / 7 处斑马线 / 1 座天桥 / 1 个码头）？**
- A）保持
- B）更密（补公交站、报刊亭、花坛、路口信号灯杆，城市更「满」）
- C）更简（只留路灯/树/斑马线，省性能也省视觉噪音）

**Q5. 车流 / 行人规模（现在 18 车 / 36 人，可调 10~30 车、10~60 人）？**
- A）保持（够热闹，draw call 不涨）
- B）拉满（30 车 / 60 人，路口更堵更活）
- C）调小（10 车 / 20 人，偏安静、省移动端性能）

> 附：如果你更在意「移动端帧率」，可以回 `Q5C + 阴影降 1024`，我在 0.4.1 里直接按档位做。

---

## 5. 工程实现（0.4.1 集成要用的部分）

**新增代码（全部在允许写入域内，未改任何既有文件）**

```
src/render/city/
  layout.ts      布局契约（塔位/层数/街道/赛道/人行道/红绿灯/相机/判定函数）—— 单一事实来源
  materials.ts   共享材质（flat / glow / water）+ 天空穹顶 + 3 风格 × 日/夜 光照表
  contract.ts    M1~M6 接口 + STYLE_META（风格名/标语）
  island.ts      六边形岛（草顶 + 4 层岩土剖面 + 3 街 + 人行道 + 标线 + 海面 + 泡沫圈）
  style-a.ts / style-b.ts / style-c.ts   4 栋塔楼生成器（各自 2 个合并网格）
  props.ts       街道道具（2 个合并网格，三风格换色）
  traffic.ts     车流 + 行人（6 个 InstancedMesh，等灯/跟车/步态）
src/city-demo/
  main.ts        场景/渲染器/光照/相机/交互/风格切换/昼夜/HUD 接线 + window.__city
  hud.ts         纯 DOM 覆盖层（左上读数 + 底部控制条，移动端适配）
  index.template.html  单文件模板（<!--CITY_BUNDLE--> 占位）
tools/build-city-demo.mjs   esbuild → iife 内联，校验零外链，打印 sha256
tools/city-shot.mjs         puppeteer + chromium 出 13 张证据图 + metrics.json
test/city-demo.test.mjs     11 项自检
```

**关键设计（性能与稳定性）**

1. **合并几何 + 共享材质**：每套风格塔楼 = 1 个不透明合并网格 + 1 个发光合并网格，道具同理；整场景只有 3 个材质（flat / glow / water）+ 天空，draw call 从「几百个 mesh」压到 18。
2. **无贴图的发光**：`MeshLambertMaterial({vertexColors, emissive:0xffffff})` + `onBeforeCompile` 把 `totalEmissiveRadiance = emissive` 改成 `emissive * vColor.rgb`，一件材质就能让任意部件按顶点色发光（霓虹/暖窗/灯带），不额外加 draw call、不用贴图。
3. **确定性**：布局是纯函数（`layout.ts`），塔楼/道具/车辆初始状态全部固定 seed → 每次打开画面完全一致，截图可比。
4. **车流**：3 条环形赛道（两直道 + 两端掉头），车辆按 `carLoopAt(s)` 取位置/朝向，永远在车道上；按 `LIGHTS` 红绿灯相位在停止线前减速停车；同道跟车保持间距。60 s 定步长仿真（dt=1/60 × 3600 帧）验证：同赛道最小车距 1.10、穿楼 0、离道 0、停在路口内 0 帧。
5. **行人**：6 条人行道折线往返 + 掉头，简单 bob/sway 步态；只在斑马线处跨车道。
6. **相机安全**：dist/pitch 硬限位；水平半径过小（在岛中央上空）时强制抬到最高塔之上（14.8），y 不低于 1.4 —— 拖到任何角度都不会钻进岛体/塔楼。

**自检怎么跑**

```bash
export PATH=/mnt/ssd/apps/nodejs_v24/bin:$PATH
cd /vol1/ai/projects/wyszz-new/frontend-rebuild-hm040-city
npx tsc --noEmit -p tsconfig.json          # 0 error
node --test test/city-demo.test.mjs        # 11/11 pass
node tools/build-city-demo.mjs             # 产出单文件 HTML
node tools/city-shot.mjs                   # 13 张证据图 + metrics.json（0 console 报错）
```

---

## 6. 已知限制 / 留给 0.4.1 的事

1. **FPS 不可当真机参考**（本机软渲染），0.4.1 集成后需在真机/移动端各测一次。
2. **城市是「原型」不是「成品」**：只有 4 栋固定塔楼 + 固定街区，没有地块/道路生长、没有昼夜循环动画（是切换）、没有天气。
3. **车辆不超车**：单车道单排、慢车会被跟成队列，偶尔出现一段空路（路口红灯时最明显）。
4. **水面是平色 + 雾**：没有真实反射/波纹；C 风格的「玻璃反射」是顶点色渐变模拟，不是环境反射。
5. **移动端**只做了布局与像素比适配（`min(dpr,2)`），未做降档（阴影 1024 / 像素比 1.5）——若 Q5 选 C 或需要保帧率，0.4.1 可加。

---

*生成时间：2026-10-22（北京时间）· 工作树 `frontend-rebuild-hm040-city`（0.3.3 基线副本，197 个基线文件 sha256 全部未变）*
