# S-28 · 城市 demo（0.4.0-r2）→ 游戏 0.4.1 迁移清单

> 目的：让 0.4.1 的集成同学**照着照做**就能把本轮 demo 的城市层接进游戏，不再重新设计。
> 口径：本清单里的「实测」数字来自 `evidence/metrics.json`（1440×900 · SwiftShader 软渲染）与 `微信可复刻审计.md`（Node 真实构建），预算按机主硬约束：**draw call ≤ 70、三角形 ≤ 150k、每模块材质 ≤3、零贴图、车人 InstancedMesh**。
> 工作树：`frontend-rebuild-hm040-city`；demo 源：`src/render/city/**` + `src/city-demo/**`；产物：`tasks-out/S-28/demo/city-0.4.0-r2.html`。

---

## 0. 一句话结论

城市层是**纯程序化、零贴图、共享材质、车人实例化**的独立模块（`src/render/city/` 9 个文件 + 1 个 StyleManager），
在 demo 里实测峰值 **B 细节派高档 ≈ 63,884 三角 / 18 draw call / 4 个可见材质**（预算 150k / 70，余量 >2.3×），
**可以直接作为 `world.ts` 里一个独立「城市层」组接入**，不需要改游戏既有渲染管线、经济、存档、调试事件。

---

## 1. 模块 → 游戏接入层总表

| # | 模块（demo 文件） | 职责 | 0.4.1 接到哪一层 | 具体接法（照做） | 是否必须 |
| --- | --- | --- | --- | --- | --- |
| 1 | `src/render/city/layout.ts` | 城市布局唯一事实来源（塔位/街道/车道/红绿灯/相机/几何判定，纯函数无 three 依赖） | 新增文件，城市层内部 | 整个目录 `src/render/city/` 原样拷进游戏；注意与游戏既有 `src/render/layout.ts`（岛屿布局）**同名不同义**，保持 `city/` 目录隔离即可 | 必须 |
| 2 | `src/render/city/contract.ts` | 模块间契约（TowerBuild / PropsBuild / TrafficBuild / CityStats / TrafficGear…） | 新增文件（类型层，不参与运行时） | 原样拷贝；**S-28 扩展的都是可选字段**（`setGear?` / `.gear` / `CityStats.gear` / `CityStats.materials` / `CityApi.setTrafficGear?` / `trafficSnapshot?` / `Hud.dispose?` / `HudHandlers.setTrafficGear?`），旧调用方零改 | 必须 |
| 3 | `src/render/city/materials.ts` | 共享材质 4 个（flat / lit / glow / water）+ 天空穹顶 + 3 风格 × 日/夜光照预设 | `world.ts` 的材质表 + 光照 | **推荐复用 `world.ts` 已有的 `matLit/matFlat/matGlow/matWater`**（构造参数一致，都是 `vertexColors + flatShading` 的 Lambert / Basic），把 city 的 `getCityMaterials()` 改成接收注入，避免多编译 4 个 shader program；天空穹顶是 `ShaderMaterial`，可独立保留（1 draw call） | 必须 |
| 4 | `src/render/city/island.ts` | 六边形岛（草顶 + 4 层岩土剖面 + 3 街 + 人行道 + 标线 + 海面 + 泡沫） | `world.ts` 场景装配（静态层） | `createWorld()` 里和既有浮空岛并列 `scene.add(island.group)`；岛尺寸/位置用 `layout.ISLAND`，可整体平移/缩放到游戏世界坐标（建议放进一个 `cityRoot` Group 便于 0.5 挂接） | 必须 |
| 5 | `src/render/city/style-a/b/c.ts` | 三套塔楼生成器（各自 2 个合并网格：不透明 + 自发光） | 城市层（三选一显示） | 由 StyleManager 统一管理，**不要单独 add 到 scene** | 必须 |
| 6 | `src/render/city/props.ts` | 街道道具（路灯/树池/长椅/斑马线/广告牌/霓虹牌/天桥/码头，2 个合并网格） | 城市层（静态层） | 同 StyleManager 管理（三风格各一份换色） | 必须 |
| 7 | `src/render/city/style-manager.ts` | 三风格运行时管理器：启动全建、切换只改 `visible`、单套失败降级、`dispose()` 干净 | `world.ts` / `app.ts` 场景装配 + **设置项** | `createStyleManager({scene, tier, buildProps, defaultStyle:'B'})`；设置项变化时 `setActive(id)`；**切风格后必须再调游戏的 `applyLighting`（demo 的 `lightingFor(style,night)`）**，manager 不碰灯光 | 必须 |
| 8 | `src/render/city/traffic.ts` | 车流 + 行人（3 车型 + 3 行人原型 = 6 个 InstancedMesh；等灯 / 跟车 / 路口占用 / 行人过街等灯；三档 关/低/高） | 城市层（动态层）+ 设置项 | `buildTraffic(scene)` → 每帧 `update(dt, t)`（放在 `app.ts` 渲染循环 `renderer.render` 之前，和 `world.update` 同级）；档位变化调 `setGear(gear)` 或 `setDensity(cars,peds)` | 必须 |
| 9 | `src/city-demo/main.ts` | demo 场景装配/交互/HUD 接线/`window.__city` | **不直接迁移**（参考实现） | 0.4.1 只需照它的顺序：island → StyleManager(prewarm 三风格) → traffic → applyLighting → 渲染循环；相机/拖拽用游戏既有 `OrbitCamera`，**不要**搬 demo 的 pointer 事件 | 参考 |
| 10 | `src/city-demo/hud.ts` | demo 的 DOM HUD（读数 + 三档/三风格按钮） | **不能迁移到小游戏**（小游戏无 DOM） | 0.4.1 的 UI 必须用游戏 `src/ui/hud.ts` 的 Canvas 2D `Layer` 重画（读数面板/三档分段控件布局可照搬 CSS 数值）；demo 的 HUD 只用于原型评审与截图 | 不迁移 |
| 11 | `tools/build-city-demo.mjs`、`tools/city-shot.mjs` | demo 单文件构建 / 截图取证 | **不迁移** | 0.4.1 走既有 `build-web.mjs` / `build-wechat.mjs`；截图脚本可留作城市层回归工具 | 不迁移 |

---

## 2. 需要新增的设置项（0.4.1 设置面板，需机主拍板文案）

| 设置键（建议） | 类型 / 取值 | 默认 | 生效方式 | 备注 |
| --- | --- | --- | --- | --- |
| `cityStyle` | `'A' \| 'B' \| 'C'` | **`'B'` 细节派** | `styleManager.setActive()` + 重算灯光 | 机主已定三风格全保留、默认 B；0.4.1 只做选择，不做 `A/B/C` 以外的扩展 |
| `cityTraffic` | `'off' \| 'low' \| 'high'` | **`'low'`（10 车）** | `traffic.setGear()` / `setDensity()` | 「关」= 0 车 0 draw call；移动端默认低档。**数量上限受 0.4.0 环线几何限制（低 10 / 高 12），原因见 §3.1 容量分析** |
| `cityPeds` | `'off' \| 'low' \| 'high'` | **`'low'`（24 人）** | 同上（车/人可分开） | demo 里是分开的两组三档；若 0.4.1 设置面板想简化为一个「车人流」总开关，属 UI 决策（见说明.md 待确认问题） |
| `cityQuality`（可选） | 跟随 `lowFx` | 自动 | `lowFx` 时阴影 1024 / 像素比 1（游戏已有逻辑，`app.ts` 第 139~141、238 行） | 城市层本身无需额外降档；若 0.4.1 要更省，可再关行人阴影（现在已关） |
| `cityEnabled`（内部调试） | `boolean` | `true` | `cityRoot.visible` + 跳过 traffic.update | 仅调试/回归用，正式包不暴露；**调试事件/调试面板改动不在 S-28 范围（禁止改调试事件）**，0.4.1 排期时再做 |

> 机主原话：「游戏内设置项留给 0.4.1」——所以本轮**只交付 demo 内切换器**，上面的设置项是 0.4.1 的施工清单。

---

## 3. 性能预算对照（实测 vs 预算 vs 余量）

> 口径：`renderer.info.render.triangles / calls`（**含阴影 pass**），1440×900，日间，默认低档；数字来自 `evidence/metrics.json`。

| 组件 | 几何三角（纯几何） | 网格 / draw call（含阴影 pass） | 材质对象 | 预算 | 余量 |
| --- | --- | --- | --- | --- | --- |
| 六边形岛 + 水面 | 1,256 | 2 | 2（lit + water） | — | — |
| 天空穹顶 | 720 | 1 | 1（ShaderMaterial） | — | — |
| 塔楼 A / B / C（每组 2 mesh） | 7,956 / 11,204 / 8,200 | 各 2（+ 阴影 2） | 2（flat + glow，共享） | 每模块 ≤3 | ✅ |
| 街道道具（每风格 2 mesh） | 11,396 | 2（+ 阴影 2） | 2（flat + glow，共享） | 每模块 ≤3 | ✅ |
| 车流 + 行人（6 个 InstancedMesh） | 低档 10 车 24 人 / 高档 12 车 40 人 | 6（车 3 + 人 3；车再 +3 阴影） | 1（flat，共享） | — | — |
| **整帧峰值（B 高档 日间）** | — | **18 call / 54,060 三角** | **4 可见材质** | **≤70 / ≤150,000** | **call 74%、三角 64% 余量** |
| 关档（车人全关） | — | 9 call（比低档少 9：3 车 + 3 人 + 3 车阴影） | 4 | — | 见 metrics |

**三风格 × 三档 实测（浏览器，1440×900，`evidence/metrics.json`；triangles/calls 含阴影 pass）**

| 风格 | 关档 | 低档 10 车/24 人 | 高档 12 车/40 人 |
| --- | --- | --- | --- |
| A 抽象几何 | 33,588 / 9 call | 40,644 / 18 call | 43,564 / 18 call |
| B 细节派（默认） | 44,084 / 9 call | 51,140 / 18 call | **54,060 / 18 call**（峰值） |
| C 霓虹夜城 | 31,676 / 9 call | 38,732 / 18 call | 41,652 / 18 call |

纹理引用 0，可见材质恒为 4（flat/lit/glow/water），三风格切换不新增材质/不重建几何（切换只改 `.visible`）。

### 3.1 车流数量为什么从 30 降到 12（0.4.0 容量分析，0.4.1 必读）

0.4.0 的环线是「单车道 + 两端 0.68 m 半径掉头半圆 + 一个平面路口 + 红灯」的最小模型，三个硬约束把通行能力钉死在约 **0.2~0.3 辆/秒**：

1. **掉头半圆单占**：半径 = 车道偏移 0.68 m，弧长 π·0.68 ≈ 2.14 m，装不下两辆 1.7 m 车，所以弧内必须单车独占（`CAP_MARGIN` + 单占 tunnel），一辆车过弧 ≈ 1.5 s。
2. **路口要等绿灯 + 对向占位清零 + 前车开出远侧斑马线**：A 组绿 10.2 s / 14 s 周期，一个绿灯每个方向实际只放 2~3 辆。
3. **掉头后到停车线的存车只有 5.7 m**（≈3 辆），排队再长就会压远侧斑马线 → 实测 14 辆以上 start 出现「停车压斑马线」。

实测（60 s 仿真，B 环线）：6 辆均速 2.26 m/s、10 辆 0.86、12 辆 0.78、14 辆 0.68、**15 辆开始压斑马线、22 辆以上永久死锁**。因此 0.4.0 取 **低 10 / 高 12**，宁少不穿模（机主第 3 条要求优先）。

**0.4.1 若要回到 20~30 辆**，需要动的是几何而不是参数（见 `说明.md` 待决问题 1）：把两端半圆改成**右转出口 + 直行段**（或加一条车道/一个路口），让掉头不再单占、存车段加长到 8 m 以上，预计通行能力 ×2.5~3。



- **零贴图**：纹理引用 0（three 内部 2 个占位纹理不算）；无网络请求、无 Worker、无外部模型。
- **实例化**：车 3 个 InstancedMesh（容量 10/型）、行人 3 个（容量 20/型），实例矩阵 `DynamicDrawUsage`，档位只改 `count` + 重排，不重建几何。
- **FPS 说明**：本机无 GPU，Chromium 走 SwiftShader 软件渲染，`metrics.json` 的 FPS 列**不代表真机**；三角/draw call/材质数与硬件无关，可验收。0.4.1 集成后在真机/微信各测一次并据实标注。

---

## 4. 微信小游戏复刻要点（详见 `微信可复刻审计.md`）

1. **零贴图**：全部顶点色 + `flatShading`；发光靠 `MeshLambertMaterial.emissive × vColor`（`onBeforeCompile` 改一行 fragment shader），不需要贴图/后处理。
2. **材质共享**：flat / lit / glow / water 四个对象全场景复用；三风格 + 道具 + 车人都不 new 材质。
3. **draw call**：合并几何 + InstancedMesh，整帧 18 call（含阴影），峰值三角 54,060（B 高档）。
   ⚠️ **three@0.186.1 自 r163 起强制 WebGL2**（源码里 WebGL1 会直接 throw，见 `微信可复刻审计.md` P0-1）：微信小游戏侧必须跑 WebGL2 适配层（基础库/机型覆盖需 0.4.1 真机验证）；若目标机型只能 WebGL1，则必须把 three 降到 r162 或换自绘实例化方案——**这是 0.4.1 的 P0 技术决策，不是 demo 能解决的**。
4. **阴影**：PCF 2048（`lowFx` 降 1024）；只有塔楼/道具/车辆投影；行人/发光网格不投影（省 3~4 个 shadow call）。
5. **平台适配**：`renderer.setPixelRatio(min(dpr,2))`，小游戏建议 `min(dpr,1.5)`；`SRGBColorSpace` + `NoToneMapping` 在微信 three 适配层可用；天空 `ShaderMaterial` 无外链、可移植。
6. **不迁移项**：demo 的 DOM HUD（小游戏无 DOM）、`window.__city` 调试 API（改由 0.4.1 的调试面板承载）。

---

## 5. 集成步骤（0.4.1 照做即可，预计 1~1.5 人天）

1. 拷贝 `src/render/city/`（10 个文件，含 `style-manager.ts`）进游戏，目录保持不变。
2. `world.ts`：`createWorld()` 里加 `cityRoot = new THREE.Group()`；`buildIsland(cityRoot)`；`styleManager = createStyleManager({scene: cityRoot, tier: 4, buildProps, defaultStyle: settings.cityStyle ?? 'B'})`；`traffic = buildTraffic(cityRoot)`；`traffic.setGear(settings.cityTraffic ?? 'low')`、`setDensity` 行人档。
3. `app.ts` 渲染循环（约第 303 行 `renderer.render(this.world.scene, ...)` 之前）：`this.world.updateCity(dt)` → 内部 `traffic.update(dt, t)`；`renderer.render` 之后取 `info` 读数给调试面板。
4. 光照：把 demo `materials.ts` 的 `lightingFor(style, night)` 搬进游戏的灯光更新函数（0.4.1 若不做夜间，只接 day 预设；夜间留给 0.5 光照系统）。
5. 设置面板：加 `cityStyle` / `cityTraffic` / `cityPeds` 三项（Canvas 2D 重画，布局照 demo `hud.ts` 的分段控件），写入存档时**不要**进经济/存档契约（属表现层偏好；若需要持久化，走既有的 UI 偏好存储**需另行评审**）。
6. 调试：内部包加 `?city=1` 与调试面板读数（tri/call/materials/车人档位）；**不要改 `src/core/debug.ts` 的既有调试事件**。
7. 回归：`npm run test:visual` / `test:public` / `regress` 全绿后再上真机；城市层新增单测可搬 `test/city-demo.test.mjs` 的关键断言（布局/预算/60 s 车流仿真）。

---

## 6. 风险与未决

| 风险 | 影响 | 0.4.1 对策 |
| --- | --- | --- |
| `world.ts` 已有同名材质/光照体系 | 材质重复会让 program/内存翻倍 | 按 §1 第 3 条注入复用，别直接 `getCityMaterials()` 新建 |
| three@0.186.1 强制 WebGL2，微信小游戏 WebGL2 覆盖不全 | 城市层在小游戏上起不来（比 InstancedMesh 更底层） | 0.4.1 先做机型/基础库覆盖验证；不达标则降 three 版本（r162 及以下）或延迟城市层上小游戏 |
| 微信 WebGL1 无 `InstancedMesh` 扩展（若最终降 r162） | 车人渲染失败 | 真机验证 `ANGLE_instanced_arrays`；兜底 = 车人数量降档/关 |
| 夜间光照未接入游戏 | demo 夜景效果在游戏里看不到 | 0.4.1 只接日间；夜间随 0.5 光照系统一起做 |
| 城市层与游戏岛屿坐标/尺度不同 | 视觉比例不对 | 用 `cityRoot.scale` / `position` 适配，别改 `layout.ts` 数字 |
| **车流上限只有 10~12 辆**（换真实车道路口前提不上去） | 0.4.1 若直接按 30 辆接，会重演 0.4.0 的堵死+压斑马线 | 0.4.1 先按低 10 / 高 12 接；要提密度先做 §3.1 的几何改造，再重跑 60 s 仿真验收 |
| 移动端阴影 2048 太重 | 掉帧 | `lowFx` 已降 1024；0.4.1 按真机再降 |

---

*本清单由 S-28 Lead 维护；数字以 `evidence/metrics.json` + `微信可复刻审计.md` 为准，若两者不一致以审计报告（Node 真实构建）为几何口径、metrics（浏览器实测）为渲染口径。*
