# S-28 说明 · 城市 demo 0.4.0-r2（运行品质 + 迁移就绪）

> 任务：在 S-26 城市 demo 基础上做「运行品质 + 迁移就绪」。
> 工作树：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm040-city`（未改游戏源码、未改 `package.json`、未动其它工作树）。
> 时间：2026-10-23 00:59 起（北京时间）。全部数字以 `evidence/metrics.json`、`evidence/性能表.md` 为准。

---

## 1. 交付物

| 内容 | 路径 |
| --- | --- |
| 单文件 demo（离线双击即开） | `tasks-out/S-28/demo/city-0.4.0-r2.html`（627,748 B，sha256 `c8636823…39099b`） |
| 截图 + 性能表 | `tasks-out/S-28/evidence/`（矩阵图 + 4 张对比拼图 + `性能表.md` + `metrics.json`） |
| 迁移清单（0.4.1 照做） | `tasks-out/S-28/迁移清单.md` |
| 微信小游戏可复刻审计 | `tasks-out/S-28/微信可复刻审计.md` |
| 开工基线 | `tasks-out/S-28/开工sha256.txt` |

下载链接（deliver-link 生成，见交付回执）：demo 与 evidence 压缩包各一条。

---

## 2. 本轮改了什么（相对 S-26）

### 2.1 三风格自由切换，默认 B（机主第 1 条）
- 新增 `src/render/city/style-manager.ts`：A 抽象几何 / B 细节派 / C 霓虹夜城三套并行建好，切换只改 `.visible`。
- **不重建几何、不新建材质、不新增 draw call**；`setStyle` 同时重算 `lightingFor(style, night)`。
- demo 内 HUD 有风格切换器；**默认 `B` 细节派**（游戏内设置项按机主决定留到 0.4.1，迁移清单 §2 已列好键名与默认值）。
- 回归：`StyleManager` 200 次切换后几何/材质计数 0 增长，三风格三角数与基线偏差 0%。

### 2.2 车辆/行人可关，升级为三档「关 / 低 / 高」，默认低（机主第 2 条）
- 契约（`contract.ts`，只加可选字段，不改既有签名）：`TrafficGear`、`TRAFFIC_GEARS`、`gearOfCount()`、`asTrafficGear()`、`TrafficSnapshot`，`TrafficBuild.setGear?()`，`CityStats.gear?/materials?`，`CityApi.setTrafficGear?/trafficSnapshot?`，`HudHandlers.setTrafficGear?`。
- 数量：**关 0/0 · 低 10 车/24 人（默认）· 高 12 车/40 人**。
  > 不是 30/60：0.4.0 环线几何的通行能力上限约 0.2~0.3 辆/秒，30 辆在 60 s 仿真里必然堵死并压斑马线（实测 22 辆以上永久死锁）。**容量分析与 0.4.1 恢复 20~30 辆的几何改造方案写在 `迁移清单.md` §3.1。**
- 车/人可分开设档（demo HUD 两组三档控件），关档 draw call 从 18 降到 9（省 3 车 + 3 人 + 3 车阴影）。
- 车与人都用 **InstancedMesh**（3 车型 + 3 人型，共 6 个 InstancedMesh），实例矩阵 `DynamicDrawUsage`，换档只改 `count` 并重排，不重建。

### 2.3 车流重写：不再穿模 / 不再互相叠（机主第 3 条）
修复前（S-26 旧车流，浏览器实测 53 次采样）：**车-车 OBB 重叠 141 次、车压行人 379 次、最小车距 0.145 m**，截图 `evidence/before-穿模-旧车流-*.png`。

修复后（同一套判据，60 s 仿真、每秒 60 帧逐帧扫描）：

| 指标 | 低档（10/24） | 高档（12/40） |
| --- | --- | --- |
| 车-车 OBB 重叠 | **0** | **0** |
| 车压行人（<0.24 m） | **0**（最小 0.401 m） | **0**（最小 0.402 m） |
| 停车压斑马线 | **0** | **0** |
| 车 OBB 出路面 | **0** | **0** |
| 同环线最小车距 | 1.31 m | 1.21 m |
| 平均车速 | 0.86 m/s | 0.78 m/s |

技术要点（`src/render/city/traffic.ts` 重写）：
1. **掉头弧单占**：半径 0.68 m 的半圆装不下两辆 1.7 m 车，弧内必须单车独占（tunnel 占用表），并且弧上硬间隔抬到 2.4 m（弧长压缩会叠车）。
2. **路口按「车身 OBB 真实压到路口框」占位**，不再用「越过停车线 + 1.94 m」的近似 —— 旧写法会让已开出去的车一直占着路口，把另一族车饿死（实测 A 绿却整段被占）。
3. **绿灯 0.8 s 起步缓冲 + 绿灯剩太少不进路口**：让上一相位已越线的车先清空，从根上消除「红灯那一刻还在路口里」被横车撞。
4. **斑马线让行**：行人带上有人就停在带外；「不把车停在斑马线上」由停车线位置 + 路口净空保证。
5. **堵车可蠕动**：满负荷时允许按 1.6 m/s 蹭到硬地板，避免 `want=0` 全员冻结的死锁。
6. **低帧率兜底**：每帧最后做一遍 OBB SAT 消重叠（真压了就沿弧长把后车回推 8 cm，最多 16 轮）。原因：软渲染 5 FPS 时一帧 dt≈0.2 s，车一步走 0.7 m，掉头弧上 yaw 差会让 OBB 角相压（实测低档 1 次 / 高档 16 次）。修完 dt=1/60、0.1、0.2、0.34 四档 × 低/高档 60 s 扫描、以及 dt 0.12~0.34 s 随机抖动 120 s 全部 0 重叠（同环线 0 / 跨环线 0） —— 即「任何帧率都不穿模」。

### 2.4 布局微调（为「不压斑马线 / 不穿楼」让路）
- 删掉 **B×C 路口北侧那条斑马线**（z=-7.9）：B 街南端改成到滨水街掉头，这条斑马线正好落在存车段里，留着必然被压。现存 6 条斑马线：A×B 四条 + C 滨水街两条。
- **B 街南端掉头点移到滨水街**（cap0 = -9.2），车身最南 -10.73 仍在 C 街路面（-10.8）内。
- **C 滨水街 0.4.0 不跑机动车**（行人有 2 条专用过街）：C 街从斑马线（±3.42）到掉头端（±4.9）只有 1.5 m 存车，物理上放不下一条环线，硬塞会压斑马线。0.4.1 补观光车的方案见待决问题 2。
- **红绿灯绿信比重配**：A/C 组绿 0~10.2 s、黄 10.2~10.9；B 组绿 10.9~13.4、黄 13.4~14。A 是主干道（两方向同时放行）给足绿灯；B 每周期只放 1 辆，2.5 s 够用；行人过 A 街的窗口 = A 红 3.1 s（够走 2.9 m）。

### 2.5 可观测性 / 迁移接口
- `window.__city.stats()` 增加 `materials`、`gear`；新增 `window.__city.trafficSnapshot()`（车/人位姿 + 当前档位），取证脚本与浏览器自检都用它。
- `main.ts`：`VERSION = '0.4.0-city-demo-r2'`，URL 参数 `?style=A|B|C`、`?cars=off|low|high`、`?peds=off|low|high`、`?t=小时` 全兼容旧参数。

---

## 3. 自检结果

- **单元/集成测试**：`node --test test/city-demo.test.mjs` → **16/16 通过**（含 60 s 逐帧全穿模扫描、跨环线 OBB、斑马线、车让人、出路面、可复现、三档开关、风格 200 次切换）。
- **截图矩阵**：`node tools/city-shot.mjs` → **39 张矩阵图 + 4 张对比拼图**，**0 console 报错、0 外网请求**，单文件 `file://` 直开。
- **预算**（浏览器实测，含阴影 pass）：峰值 **54,060 三角 / 18 draw call / 4 可见材质 / 0 纹理**，预算 ≤150k / ≤70，余量 64% / 74%。
- **风格切换无泄漏**：200 次切换后 geometries/materials/textures 计数零增长。
- **可复现**：同参数同 dt 两次 60 s 仿真终态逐车一致。

> FPS 说明：本机无 GPU，Chromium 走 SwiftShader 软件渲染，`metrics.json` 里的 FPS **不代表真机**，仅作相对参考；三角/draw call/材质数与硬件无关，可验收。

---

## 4. 已知取舍（本轮主动做的减法）

1. **车流上限 10/12 辆**（原计划 30/60）：几何容量所限，宁少不穿模。恢复方案见 `迁移清单.md` §3.1。
2. **C 滨水街无机动车**：同上，属几何不可能，0.4.1 用观光车/单行道解决。
3. **B×C 北侧斑马线删除**：行人动线仍闭合（B 街两侧各有斑马线，C 街有 2 条）。
4. **HUD 仍是 DOM**：小游戏无 DOM，0.4.1 必须用 Canvas 2D 重画（P0-2，见审计报告）。
5. **three@0.186.1 强制 WebGL2**：小游戏侧 P0 风险，需 0.4.1 真机验证或降 three 版本。

---

## 5. 需要机主拍板的 5 个问题（每个都给了选项与建议）

**Q1. 车流密度：接受 0.4.0 的「低 10 / 高 12」，还是为了密度改几何？**
- A. 接受（建议）：0.4.0 先保「不穿模、不压斑马线」，0.4.1 再提密度。零返工。
- B. 现在改几何：把两端掉头半圆改成右转出口 + 直行段，存车段加到 8 m 以上，预计可回到 20~30 辆。代价：`layout.ts` 布局与三风格塔楼/道具避让要重排，约 +1~1.5 人天，且要重跑全部截图。
- C. 折中：只改 B 街（次干道）为直行贯通，A 街保持现状，密度提到 16~18 辆。代价：B 街掉头区在滨水街的布景要重做。

**Q2. C 滨水街要不要机动车？**
- A. 0.4.0/0.4.1 都不要（建议）：滨水街保持「步行 + 观光」气质，行人有 2 条专用过街，视觉上不空。
- B. 0.4.1 加 1~2 辆慢速观光车（单向循环，20 km/h 以下）：需要在 C 街两端各加一个小回车场（约 +0.5 人天）。
- C. 把 C 街并进 A 环线（车流绕滨水街走一段）：会破坏「滨水步行街」定位，不推荐。

**Q3. 红绿灯绿信比（A 10.2 s / B 2.5 s）是否可接受？**
- A. 保持（建议）：A 主干道顺畅、B 街每周期 1 辆，符合「小街区一支路」的体感。
- B. 改 A 12 s / B 1.5 s：A 更顺，B 排队更长（B 只有 2 辆车，观感影响小）。
- C. 引入「B 街只出不进」单行：A 完全不被打断，但 B 街看起来像单行道，需机主确认城市设定。

**Q4. HUD/设置面板迁移方式（0.4.1 P0）？**
- A. Canvas 2D 重画（建议）：复用游戏 `src/ui/hud.ts` 的 `Layer`，与现有 HUD 同一套绘制体系，小游戏可用。
- B. 小游戏侧自绘 overlay：性能最好但两套 UI 代码，维护成本高。
- C. 只保留 H5 版 HUD，小游戏版先不做城市面板：最省事，但小游戏用户无法切风格/关车流。

**Q5. 默认风格是否长期定 B（细节派）？**
- A. 一直默认 B（建议，机主已定）：风格差异最大、最像「城市」。
- B. 按设备性能自动降级：低端机默认 A（三角少 ~20%），高端机 B。
- C. 进 0.4.1 设置项由玩家选，首次进入按 B：与机主「设置项留 0.4.1」一致。

---

## 6. 下一步（0.4.1）

1. 按 `迁移清单.md` §5 的 7 步把 `src/render/city/` 接进游戏 `world.ts` / `app.ts`。
2. 加 `cityStyle` / `cityTraffic` / `cityPeds` 三项设置（Q4 拍板后选 Canvas 2D 方案）。
3. 小游戏 WebGL2 真机验证（P0-1）；不达标则降 three 到 r162 或延迟城市层上小游戏。
4. 想提密度：按 Q1 选 B/C 做几何改造，然后重跑 60 s 车流仿真与截图验收。

---

*本说明由 S-28 Lead 维护。数字口径：几何=Node 真实构建（审计报告），渲染=浏览器 `renderer.info`（metrics.json）。*
