# 性能优化方案 与 交互控制逻辑

目标设备：PICO Neo 3（骁龙 XR2），PICO 浏览器 WebXR 沉浸模式，目标 72Hz 稳定。

---

## 一、实测预算

场景就绪后页面左上角会实时显示这几个数（桌面 2D 和头显里都能看）：

```
场景就绪 · 时刻 8.5 时 · 阴影 烘焙 · 太阳 103,100,-72 · 光强 1.30
· 三角面 34670 · draw call 68
```

| 指标 | 实测 | 移动 XR 参考线 |
|---|---|---|
| 三角面 | **33k ~ 38k** | < 100k 安全 |
| draw call | **47 ~ 68** | < 100 安全 |
| 贴图 | 8 张程序化，最大 1024²（阴影）+ 512²（地面），其余 256² | — |
| 材质数 | 9 个，全场景共享 | — |
| 后处理 | **无** | 移动 XR 上 bloom/SSAO 性价比极低 |

单帧 CPU 侧只有：一次摇杆位移积分 + 射线检测（有白名单）+ 无逐帧阴影开销。

---

## 二、六条具体优化及其理由

### 1. 重复构件全部实例化（InstancedMesh）

檐柱、金柱、斗拱、望柱、廊庑柱这五类构件加起来 300 多个。
逐个建 Mesh 就是 300+ 个 draw call；用 `THREE.InstancedMesh` 之后**每类只占 1 个 draw call**。

```
望柱 ~150 个  → 1 draw call
斗拱 ~120 个  → 1 draw call
檐柱/金柱 ~50 个 → 1 draw call
廊庑柱 ~50 个 → 1 draw call
```

这是整个场景从"几百 draw call"降到 68 的主要原因。

### 2. 阴影：太阳投影烘焙，而不是实时阴影贴图

**这是本项目最重要的一条取舍。**

先说结论：**实时阴影贴图在这套技术栈里没跑通，而且对这个场景本来就不划算。**
排查过的具体原因（都验证过，不是猜的）：

- A-Frame 的 `shadow` 系统会在 init 时把 `renderer.shadowMap.enabled` 置为 `false`，
  只有走它的 `shadow` 组件（实体上写 `shadow="cast: true"`）才会记账打开。
  本项目几何是直接用 three 建的、`castShadow` 也是直接设的，绕过了那套记账。
- 手动打开总开关后仍然无效——因为 three.js 会把「阴影是否启用」**编进着色器程序并缓存**，
  材质在开关之前就编译好了，之后改 `enabled` 不会触发重编。
- 再往后强制重编材质、手动设置并 `updateProjectionMatrix()` 阴影相机，实测仍未出影。

试到这一步我停手了，因为**即使修好，实时阴影贴图对"静态场景 + 移动 GPU"也是最不划算的一档**：
每帧一次额外深度渲染 + 每个像素一次阴影采样，而收益只是"影子会动"——
可这个场景的影子**只在太阳移动时才需要变**。

所以改成**太阳投影烘焙**（`app.js` 的 `bakeShadows()`）：

1. 每个构件用「俯视矩形 + 顶面高度」近似成一个投影体（`PALACE.casters()`）
2. 沿太阳方向把矩形拉伸成阴影多边形（8 点凸包），画进离屏画布
3. 先画成**不透明遮罩**，再整张按统一 alpha 铺一次——避免多构件重叠处越叠越黑
4. 每个接收面（广场 + 三层台基顶）各有一张 1024²/256² 贴图，做成贴花盖在面上
5. 太阳一动就重烤；时段平滑过渡期间按 **~11Hz 节流**

| | 实时阴影贴图 | 烘焙投影（当前方案） |
|---|---|---|
| 每帧 GPU 成本 | 一次深度 pass + 逐像素采样 | **0**（就是一张普通贴图） |
| 受太阳变化影响 | 自动 | 重烤，约 3~8ms/次 |
| 精度 | 逐像素 | 轮廓级（矩形近似 + 高斯模糊） |
| 移动端适配 | 差 | **好** |

**代价（明确记下来）**：只对 `PALACE.casters()` 清单里的构件生效；
是硬边+模糊，不是逐像素精确阴影；镂空（格扇门）不会透光。
将来若需要这些，再换回实时阴影贴图。

### 3. 全部贴图程序化生成，零网络请求

8 张贴图（金砖、汉白玉、朱红墙、琉璃瓦、菱花格扇、彩画、天空渐变、UI 面板）
全部用 Canvas 画出来。好处：

- **零网络请求**：头显首屏不用等下载，加载时间就是本地计算时间
- **内存小**：512² 的 canvas 只有 1MB，而一张 2K 实拍贴图解压后是 16MB
- **天然可平铺**：用取模噪声，接缝处连续
- **可参数化**：改颜色/密度只改代码，不用重新导出资源

代价是质感上限低于实拍扫描。这是刻意的取舍——**先保帧率，再谈质感**。

### 4. 关闭阴影贴图系统本身

`index.html` 里写死 `shadow="enabled: false"`。
既然阴影走烘焙，就没必要让 three.js 每帧走一遍阴影贴图流程（哪怕没有投射体，
它也会做一次灯光阴影更新和 uniform 上传）。

### 5. 渲染器设置针对移动端

```
renderer="antialias: false; colorManagement: true; precision: medium; logarithmicDepthBuffer: false"
```

- `antialias: false`：WebXR 模式下抗锯齿由浏览器给 XR framebuffer 做，
  再开一层 MSAA 是纯浪费
- `precision: medium`：片元着色器用中精度。注意 A-Frame 的值要写 `medium`，
  写 `mediump` 会被它拼成 `mediumpp` 而回落成 lowp（这个坑踩过）
- `logarithmicDepthBuffer: false`：深度缓冲对数化会拖慢移动 GPU，
  用 `near: 0.1 / far: 600` 的普通深度就够
- 相机 `far` 收到 600，天空球半径必须跟着落在里面（默认 5000 会被裁掉）

### 6. 雾同时承担"氛围"和"隐藏远景"两个职责

指数雾 `density 0.0030 ~ 0.0055`（画质档可调）。它既是北京特有的霾感，
也让 300 米外的边界自然淡出——**不需要把远景裁掉，也不需要远处高模**。
廊庑、宫墙、太和门都用低模即可。

---

## 三、画质档位

场景内控制台的「画质」三个按钮，或 URL 参数 `?q=low|medium|high`：

| 档位 | 雾密度 | 烘焙阴影 |
|---|---|---|
| 低 | 0.0055 | **不显示**（省一层透明叠绘） |
| 中（默认） | 0.0038 | 显示 |
| 高 | 0.0030 | 显示 |

降档只降"远景通透度"和"阴影贴花"，**不动几何和光照**——
这样降档后画面观感变化最小，但 GPU 压力确实下降。

---

## 四、交互控制逻辑

### 4.1 输入 → 行为的完整映射

| 输入 | 行为 | 说明 |
|---|---|---|
| 头部转动（6DoF） | **环视** | 浏览器原生，代码零参与 |
| 左摇杆 | **平移** | 方向跟随当前视线偏航角 |
| 左摇杆横向推到底 | **左转 30°** | 防误触：需超过 0.75 死区，且转一次后要回中 |
| 右摇杆 | 同上（转身） | 左右手分工，任一只手持柄都能操作 |
| 视线准星停在地面 1.6 秒 | **瞬移** | 有落点指示环 |
| 手柄指向地面 + 扣扳机 | **瞬移** | 与上一条等价 |
| 视线/手柄指向场景内按钮 | **切换时段 / 视角 / 画质** | 按钮有 hover 高亮 |

### 4.2 平移为什么"跟着视线走"

摇杆的"前"不是世界坐标的 -Z，而是**头显当前朝向的水平投影**：

```
yaw      = 从相机世界四元数里取出偏航角
forward  = (-sin(yaw), 0, -cos(yaw))
right    = ( cos(yaw), 0, -sin(yaw))
位移量    = forward * (-摇杆Y) + right * 摇杆X，再乘以速度×dt
```

这样低头看地时按"前"仍然是水平前进，不会一头扎进地里；
侧身穿行时按"前"也符合直觉。这是 VR 里最通用的做法。

### 4.3 落地高度怎么算

不能只把 x/z 挪过去——三台有 6 米高。所以每次移动后都重新求一次地面高度：

```js
groundHeight(x, z)   // 依次判断是否落在第三层/第二层/第一层台基内，返回对应高度
rig.position.y = groundHeight(x, z) + 0.02
```

于是从广场走到台上是连续的，瞬移到台基上也会自动站到正确高度。

### 4.4 时段切换的过渡

点「晨曦/正午/黄昏/夜色」不是瞬间跳变，而是 **1.3 秒缓入缓出**（smoothstep）插值：
太阳高度角、方位角、色温、强度、天空渐变、雾色**同步**过渡。

太阳位置由时刻反推：

```
day   = (hour - 5.5) / 13         // 5:30 日出 → 18:30 日落
仰角  = sin(π·day) × 58°
方位  = lerp(东 102°, 西 -102°, day)   // 建筑朝南，故 +x 为东
```

阴影重烤与光照过渡共用同一个时刻值，所以**影子会跟着太阳一起转**。

### 4.5 为什么用瞬移 + 摇杆两种移动方式

- **摇杆平移**：连续、自由，适合慢慢走近看建筑细节（近景）
- **瞬移**：不会前庭不适，适合快速换到远处的观察点（远景）

两种并存而不是二选一，因为课堂上的使用者既有第一次戴 VR 的，也有熟练的。

### 4.6 界面为什么必须做进 3D 场景

WebXR 沉浸模式下浏览器**不渲染 DOM 覆盖层**。
参考视频里那两侧的 HTML 图文面板能录到，是因为当时还在桌面 2D 模式；
真戴上头显进沉浸模式，HTML 面板会全部消失。

所以控制台、提示文字、按钮标签**全部用 Canvas 画成贴图贴进 3D 场景**。
顺带解决了另一个问题：A-Frame 默认字体不含中文字形，直接用 `a-text` 写中文会显示成方块。

---

## 五、可调参数速查

| 想调什么 | 改哪里 |
|---|---|
| 建筑比例 | `palace.js` 顶部的 `C` 常量表 |
| 屋顶举折曲线 / 起翘 | `C.lowerRoof.curve / .uplift`，`C.upperRoof.curve / .uplift` |
| 阴影深浅 | `app.js` 的 `SHADOW_ALPHA` |
| 阴影柔和度 | `bakeShadows()` 里的 `blur(...)` |
| 阴影参与范围 | `palace.js` 的 `casters()` / `receivers()` |
| 移动速度 / 转身角 / 死区 | `index.html` 上 `stick-locomotion` 的属性 |
| 瞬移凝视时长 | `index.html` 上 `cursor` 的 `fuseTimeout` |
| 雾 / 画质 | `app.js` 的 `QUALITY` |
