# A-Frame 实践 · 操作指南（温馨小屋 ↔ 后花园）

> 对应作业要求：① 能在 PICO Neo 3 里打开 ② 停留圆环 1.2 秒 / 点击标签跳转
> ③ 右上角显示 FPS / DrawCall / 三角面 ④ 能"走进去"的场景 + 3D 物体姓名牌 ⑤ 能进 VR

---

## 1. 作品里有什么

| 要求 | 实现 | 在哪里看 |
|---|---|---|
| 走进去的场景 | 场景 A 温馨小屋（8m×8m 室内）+ 场景 B 后花园（16m×16m 露天），WASD/摇杆走路 | 进页面就是小屋 |
| 3D 姓名牌 | 3D 立式门牌（底座+立柱+牌面），小屋进门正前方偏左 | 小屋内视线左前方 |
| 跳转 | ① 视线停在白色圆环 1.2 秒 ② 鼠标点击圆环/标签 | 圆环在小屋北墙 / 花园北侧 |
| 读数 | 右上角面板，VR 内头顶也有同源面板 | FPS / DrawCall / 三角面 |
| 进 VR | 右下角「进入 VR」按钮（PICO 浏览器里是戴上门显直接进入） | — |

场景切换有 0.2 秒黑场过渡；左上角标签实时显示当前场景名。

---

## 2. 素材来源与下载操作（已替你完成，留档备查）

本项目所有模型来自 **Kenney**（kenney.nl），**CC0 授权 = 免署名、可商用、可交作业**：

| 素材包 | 网址 | 用到的模型 |
|---|---|---|
| Furniture Kit | `https://kenney.nl/assets/furniture-kit` | 沙发、茶几、书架、餐桌、椅子、吧椅、落地灯、边桌、盆栽、长椅、花盆植物 |
| Nature Kit | `https://kenney.nl/assets/nature-kit` | 树×3 种、灌木、石头、草丛、花、蘑菇、栅栏、木牌 |

**手工下载流程（其他站同理，如 Poly Pizza / Poly Haven）：**
1. 打开素材网址 → 点 **Download** 下载 zip；
2. 解压，进入 `Models/GLTF format/` 文件夹（只要 `.glb` 文件）；
3. 把需要的 `.glb` 复制到 `E:\WebXR\aframe-practice\assets\models\`；
4. 文件名对应关系写在 `index.html` 的 `SLOTS` 表里（约第 699 行），改成你要的名字即可。

> 当前 `assets/models/` 已放好 32 个 GLB（共约 300 KB，全部低模，手机头显无压力）。
> 就算把模型全删光，页面也不会报错——代码会自动退回几何占位块。

### 换素材时的注意事项（踩过的坑）

1. **优先选「无内嵌纹理、用顶点色」的低模**（如 Kenney）。100+ 个模型的场景在 PICO 上依然流畅。
2. 模型会**自动缩放到 `SLOTS` 表里第 4 列的目标高度**，不用手工对齐比例；
   但要求模型是「单件、朝上、底部大致在 y=0」的姿态，否则缩放后姿态会歪。
3. 换 `.glb` 后若模型看不到，先按 `F12` 看有没有 `model-error`——文件名大小写错了最常见。
4. 带贴图的 glTF 用 `.glb`（贴图打包在一个文件里）比 `.gltf + 一堆 .bin/.png` 省事。

---

## 3. 电脑上自测（2 分钟）

```bash
cd E:\WebXR
python -m http.server 8010
```

浏览器打开：`http://localhost:8010/aframe-practice/index.html`

- **环视**：按住鼠标左键拖动
- **走路**：`W A S D` 或方向键
- **跳转**：把准星对准白色圆环停 1.2 秒（圆环会放大，走完进度即跳）；或直接点击圆环 / 下方文字标签
- 从花园跳回：同样操作花园里的白色圆环

**检查控制台（F12）**：应打印 `✓ A-Frame 双场景已就绪`，无红色报错。

---

## 4. PICO Neo 3 上机（4 步）

1. **同一 WiFi**：PICO 和电脑连同一个路由器/WiFi。
2. **查电脑 IP**：`ipconfig` → 看「IPv4 地址」，如 `192.168.1.100`。
3. **头显浏览器打开**：PICO 里开浏览器，地址栏输入
   `http://192.168.1.100:8010/aframe-practice/index.html`
   （换成你的 IP；**必须 http:// 开头完整输入**）
4. **进入 VR**：页面加载后点右下角「进入 VR」图标（或浏览器会自动提示进入沉浸模式）。
   - 视线中央有白色小圆点准星，对准白色大圆环**停住 1.2 秒**即跳转；
   - 左手摇杆可前后左右走路；
   - 头顶右上方有一块 VR 内读数板（FPS / DrawCall / 三角面），和电脑上同源；
   - 退出：按手柄 PICO 键 → 退出沉浸模式。

> ⚠️ WebXR **必须 http:// 或 https://** 打开。直接双击 html（file://）进 VR 100% 失败。

---

## 5. 读数面板与「对照实验」

右上角面板数字来自 `renderer.info`（和 VR 内面板同源，绝不会出现两边对不上）：
- **FPS**：每 0.5 秒刷新一次
- **DrawCall**：本帧 draw call 次数
- **三角面**：本帧渲染三角形数（约 1.3 万，PICO Neo 3 上很轻松）

对照实验（对应任务 A 的读数对照思想）：把浏览器窗口缩很小 → DrawCall/三角面**基本不变**，
因为 three.js 的 draw call 取决于场景内容而非画布大小（FPS 会升高，因为填充的像素少了）。

---

## 6. 改成自己的姓名学号

打开 `index.html`，搜 `学号 2024001`（约第 216 行），改成：

```html
<a-plane id="nameFace" cn-text="value: 学号 2024XXXX · 你的名字; fg: #1b2430; bg: #f6f1e7; bgOpacity: 1; font: 78; h: 0.40" ...
```

中文直接写，canvas 会现画现贴（A-Frame 内置 a-text 不支持中文，所以专门写了 cn-text 组件）。

---

## 7. 卡住了怎么定位（能定位 = 达标线第 5 条）

| 症状 | 环节 | 解决 |
|---|---|---|
| 电脑浏览器打开白屏/进 VR 按钮灰色 | 环境 | 确认用 `http://localhost:8010/...` 不是 `file://` |
| PICO 打不开页面 | 环境 | 两台设备同一 WiFi？IP 抄对没？电脑防火墙放行 8010 端口没？ |
| 页面开了但景物全是色块 | 作品 | 模型没加载（正常容错），检查 `assets/models/` 是否在原位 |
| 控制台红色报错 | 作品 | 把报错第一行抄下来（含文件名+行号） |
| 进入 VR 后画面不动/黑屏 | 设备 | PICO 浏览器版本过旧 → 检查系统更新；或换个房间重进 |
| 视线停圆环不跳 | 作品/设备 | 必须停满 1.2 秒且准星在环上；确认页面完全加载（左上角有场景标签） |

---

## 8. 文件结构

```
E:\WebXR\aframe-practice\
├── index.html              ← 作品本体（双击无效，务必 http 打开）
├── libs\aframe.min.js      ← A-Frame 1.8.0（已下载，离线可用）
├── assets\models\*.glb     ← 32 个 Kenney CC0 模型
├── shots\*.png             ← 截图
└── 操作指南-AFrame.md       ← 本文件
```

---

## 9. 已验证记录（交付前实测）

用无头 Edge（SwiftShader 软渲染）+ 注入诊断探针，对页面做了**真实渲染验证**：

| 检查项 | 结果 |
|---|---|
| 场景加载 | ✓ 两场景均 `hasLoaded: true` |
| 控制台报错 | ✓ **0 条** error / warn / model-error |
| 模型加载 | ✓ 23/23 条 SLOTS 引用全部加载成功 |
| 模型贴地 | ✓ 小屋模型 `worldY = 0.00`；花园模型 `worldY = 0.00`（激活后） |
| 场景隔离 | ✓ 未激活场景模型 `worldY = -300`（正确藏于地下） |
| HUD 一致性 | ✓ HUD 显示值 = `renderer.info` 实际值（42 calls / 13.2k tris） |
| 中文姓名牌 | ✓ canvas 贴图生成成功，画面可见「学号 2024001 · 张同学」 |
| 注视光标 | ✓ `cursor fuse: true; fuseTimeout: 1200` 生效 |
| 跳转 | ✓ 场景 A↔B 切换后 tag / visible / 位置 / 灯光全部正确 |
| 截图 | `shots/场景A_温馨小屋.png`、`shots/场景B_后花园.png` |

### 开发中修掉的两个真实 bug（留档，避免复发）

**① `a-sky` 半径超出相机远裁剪面 → 天空全黑**
A-Frame 的 `a-sky` 默认 `radius = 5000`，而相机 `far = 200`，整个天球被远裁剪面切掉。
修复：`<a-sky id="sky" radius="180" src="" color="#8fc0e0">`。

**② `fitModel` 用世界坐标量尺寸 → 模型被顶到几百米高空**
模型是异步挂载的；`worldGarden` 在 `boot()` 里已被设为 `position: 0 -300 0`（用来隐藏），
于是 `Box3.setFromObject()` 量出的 `minY ≈ -300`，`position.y = -minY × k` 把树顶到了天上。
修复：在模型**自己的父级局部坐标系**里遍历顶点算包围盒（先乘 `matrixWorld` 再乘父级矩阵的逆），
而不是用世界坐标。同时把缩放做成**幂等**的（以初始尺寸为基准），避免父子多次调用时重复放大。

> 这两个 bug 在纯静态代码检查里都发现不了——必须真实渲染 + 读回 WebGL 帧才能暴露。
> 也提醒：**不要只信无头截图**。`--screenshot` 在 `--virtual-time-budget` 下可能截到模型加载前的旧帧；
> 用 `renderer.render()` 后立即 `canvas.toDataURL()` 主动抓帧，才是地面真值。

---

## 10. 注视交互（当前实现，2026-10-13 第三轮修订）

### 10.1 三条规则

| 项 | 现在是怎么做的 |
|---|---|
| **注视有效区** | **白色圆环以内整块圆面**都算命中：判定体是半径 **0.56 米** 的实心圆盘 `a-circle`（白环本体只占 0.395~0.485 米），视线落在圆环内任意位置都行，不用对准那圈细线 |
| **1.2 秒进度可视化** | 注视开始后，**白环立刻压暗成灰白**，一条**黄色弧带**从 **12 点方向顺时针**长出来；走满一整圈 = 1.2 秒 = 跳转。弧带比白环略宽（0.105 米 > 0.09 米），所以填到哪就把白环盖到哪，视觉上就是"白环正在被黄色填满"。弧头还有一颗亮珠标出当前位置 |
| **视线移开** | 立刻清零：黄弧消失、白环恢复纯白、准星缩回原大小 |

进度同时会喂给三处，所以**任何一处看到的进度都一致**：
① 白环上的黄弧；② 屏幕中央的准星（逐渐放大 1.0→1.5 倍）；③ 注视文字标签时，标签的透明度逐渐变亮。

### 10.2 为什么"实心圆盘"这次不会再乒乓跳

第一版用圆盘时踩过坑：跳到对面场景后，圆环恰好落在**新的出生视线正中**，
判定区把视线接住 → 1.2 秒后又被原路弹回来，两个场景来回跳。

现在不靠缩小判定区，而是加一条**状态规则**（`gaze-dwell` 里的 `armed`）：

> **跳转完成后，必须先把视线移开所有热点一次，才允许重新开始计时。**

所以跳过去以后，即使视线还压在环心，也不会自己再触发一次；
你自然地把头转开、再转回来看圆环，才会计时。这样既保住了"整块圆面都能瞄"的宽松手感，
又不会乒乓跳，比原来的"1.5 秒时间冷却"更符合直觉（时间冷却在你马上想看回环时会失效）。

### 10.3 为什么自己写 `gaze-dwell`，不用 A-Frame 的 `fuse`

A-Frame 的 `cursor` 组件自带 `fuse: true; fuseTimeout: 1200`，第一版就是用它。
两个问题：

1. 它只在**注视目标发生变化**的那一刻派发 `fusing`，取消 / 完成都跟它内部的
   `click` 绑在一起，想单独实现"跳转后必须先移开视线"很别扭；
2. 电脑上 `rayOrigin: mouse` 的光标**根本不派发 `fusing`**，行为两头不一致。

现在 `gaze-dwell` 挂在 `#head` 上，每帧从相机正中发一条射线（头显里就是视线正中），
自己算命中、自己算进度。逻辑全在明面上，PC 和头显表现一致，
也方便写探针直接驱动它做单元测试。

### 10.4 进度弧为什么从「贴图」改成「几何」

第一版进度弧是 **canvas 画弧 → `THREE.CanvasTexture` → 贴到 `a-plane`**，结果弧完全不显示。

**根因**：`CanvasTexture` 只在构造函数里把 `needsUpdate` 置一次 `true`；
之后每次重画画布，都必须**手动** `tex.needsUpdate = true`，GPU 才会重新上传贴图。
漏掉这一行，GPU 上就永远是最初那张空白图——
表现正是"注视了、也跳转了，但黄色进度弧完全不出现"。

现在改成**直接生成环形几何、逐帧改写顶点**：
不依赖贴图上传，也不依赖着色器对 `map` 的支持，颜色最纯、边缘最锐利；
每帧只改 57 组顶点，CPU 开销可以忽略。
（留档提醒：**以后凡是 canvas 动态贴图，改完画布记得 `needsUpdate = true`**。）

### 10.4b 为什么第二次改完还是看不见 —— 深度测试与 Z 位置的坑（第四轮修订）

改成几何弧之后**仍然看不见**，用最小复现页逐个变体排查，定位到两个叠加原因：

| 变体 | 改动 | 结果 |
|---|---|---|
| A | 原样（弧 `z=0.055`，`renderOrder=3`，`depthWrite:false`） | **看不见** |
| C | 把 `renderOrder` 提到 2 | 更看不见（提前画、被后画的白环盖住） |
| D | 关掉白环 | 弧清晰可见 |
| E | 弧 `z` 往前推 | 可见但位置飘 |
| **F（最终）** | **弧 `z` 推到 +0.080（白环在 z=0），`renderOrder=5`，材质恢复默认 `depthTest`** | **稳定可见** |

**根因**：弧和白环几乎在同一平面，`-z` 方向的浮点深度值过于接近，
GPU 的深度精度（尤其 `logarithmicDepthBuffer` 关闭时）无法稳定区分谁在前，
同一个弧有时赢有时输 → 表现为"弧时有时无 / 完全看不到"。

**最终方案**：不靠渲染顺序，而是**用物理 Z 距离分出前后** —— 把弧实体 `position` 的 z 从 `0.055` 改成 **`0.080`**，
比白环（z=0）明确靠近观察者 8 cm（场景中圆环总直径约 0.9m，8cm 是肉眼不可分辨、但对深度缓冲绰绰有余的距离）。
`renderOrder` 保留 5 只作为二次保险。**教训：同平面叠层不要指望 renderOrder，要把 Z 拉出可见间距。**

### 10.5 涉及的元素（改参数时照着这张表找）

| 元素 id | 作用 | 关键参数 |
|---|---|---|
| `ringHouseHit` / `ringGardenHit` | 注视命中区（**实心圆盘 = 白环以内整块都算命中**） | `radius="0.56"`，`opacity: 0.09` 的淡金光晕 |
| `ringHouseTorus` / `ringGardenTorus` | 白色圆环本体（注视目标） | `radius 0.44`、`radius-tubular 0.040`（白环管半径 0.04m，外缘 0.48m） |
| `ringHouseProg` / `ringGardenProg` | 黄色进度弧 | `position z=0.080`、`ring-progress="r: 0.44; tube: 0.115; color: #ffc21f"` |
| `gazeCursor` | 屏幕中央准星 | 由 `gaze-dwell` 缩放；`cursor="fuse: false"` |
| `#head` 上的 `gaze-dwell` | 注视计时总控 | `gaze-dwell="dur: 1200; far: 30"`（`dur` 就是想要的秒数×1000） |

想调"要停多久"，只改 `gaze-dwell="dur: ..."` 一个地方；
想调"好瞄程度"，只改两个 `*Hit` 的 `radius`（0.56 已经把白环外层 0.48 完整包住，圆环以内全部算命中）。

### 10.6 电脑上肉眼验证进度弧：按 `P` 键

无头环境无法伪造"注视中"状态，所以页面加了一个调试开关：

> **按键盘 `P`** → 进度弧依次定格在 **0% → 50% → 100% → 关闭**，循环切换。

每次切换会弹提示，两个场景的圆环同时生效。这样可以直观检查弧的粗细、颜色、起点方向对不对，
而不用真的把屏幕中央对准圆环等 1.2 秒。确认外观没问题后，按到"关闭"即可恢复正常注视逻辑（不影响头显）。

