# 19 · L3 报告（任务一 hall.glow 视觉着色 / 任务二 居民点击区）

* 任务编号：**L3**（任务书：`docs/11-0.1收尾任务书-分级.md` §5）
* 工作副本（本次唯一改动范围）：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm-work-L3/`
* 只读参考（**未改动**）：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm/`
* 执行环境：Node **v24.15.0**（`/mnt/ssd/apps/nodejs_v24/bin`）、npm 11.12.1、chromium（由 `test/lib.mjs` 的 `launch()` 探测 `/usr/bin/chromium`）
* 渲染环境：**ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero)), SwiftShader driver)**，`lowFx=true`、`pixelRatio=1`、视口 390×844
  → **这是软件渲染（SwiftShader），不是真机、也不是真 GPU**；所有截图、draw call / 三角形 / programs 数字与帧率均来自该环境。
* 本报告中的所有数字均为本次实际运行所得；不确定的地方在 §9「诚实记录」里明确标注。

---

## 1. 结论

| 任务 | 结果 | 说明 |
| --- | --- | --- |
| 任务一 · hall.glow 视觉着色 | **完成** | 升级成功时在市政厅屋顶外圈出现金色光环（复用已有材质对象，未新增世界材质）；画面像素、draw call、三角形三项均可测量。 |
| 任务二 · 居民点击区 | **完成（部分达成）** | 4 个居民中，原本"被**隐形**市政厅命中盒挡住"的那 1 个（居民#2）中心点恢复自命中；另一个（居民#3）是**被可见地形/建筑真实遮挡**，按任务书要求**刻意保留**该语义。默认视角自命中率 2/4 → 3/4。 |
| 回退 | **无** | 三次全量回归（R0/R1/R2）全部 PASS，没有触发任何回退。 |
| 待决问题 | 3 项 | 见 §8；均不需要改 `src/core`，但其中 1 项若产品改口径则超出 L3 授权。 |

改动文件共 **4 个**（源码 2 + 测试 2），`src/core/` **零改动**：

| 文件 | 改动性质 |
| --- | --- |
| `src/render/world.ts` | 任务一（光晕渲染）+ 任务二（拾取最近命中规则） |
| `src/app/app.ts` | 任务一（升级成功即时同步光晕）+ 调试接口追加（`setHallGlow`、`pickAll` 诊断字段） |
| `test/t-visual.mjs` | **纯追加** 66 行（T12a–T12d） |
| `test/t-gameplay.mjs` | **纯追加** 51 行（T13a–T13c） |

---

## 2. 任务一：hall.glow 视觉着色

### 2.1 改动前（问题）

`hall.glow` 只在 `src/app/app.ts:221` 被赋值为 1（升级成功），在 `src/render/world.ts` 每帧衰减，除此之外**从未参与任何渲染**：

```ts
// src/render/world.ts:351（改动前，唯一涉及 glow 的渲染代码）
if (hall.glow > 0) { hall.glow = Math.max(0, hall.glow - dt * 1.2); }
```

`glow` 只通过调试接口 `hallBounce()`（`src/app/app.ts:292`）暴露，画面上没有任何对应着色 —— 与任务书描述一致。

### 2.2 改动后（diff，源码 2 个文件）

`src/render/world.ts`（相对原目录）：

```diff
@@ interface World
   setLevel(level: number): void;
   update(dt: number, t: number): void;
+  /** 只把 hall.glow 同步到光晕（不推进世界）：update 每帧调用，调试/测试也可单独调用。 */
+  syncGlow(): void;
   pick(raycaster: THREE.Raycaster): PickResult;

@@ 材质（把 matDiamond 提前，位置不变、数量不变）
   const materials = [matLit, matFlat, matGlow, matWater, matCloud];
+  // 金色无光照材质：居民可点提示菱形 + 市政厅升级光晕**共用同一个材质对象**，
+  // 因此不新增世界材质（口径见 docs/01 §5：世界材质对象数 = 7）。
+  const matDiamond = new THREE.MeshBasicMaterial({ color: 0xffe27a });
+  materials.push(matDiamond);
@@ 市政厅（居民段里原来的 matDiamond 定义被删除，只是搬家）
   let beads = meshOf(buildHallBeads(1), matGlow, CITYHALL_TAG, false, false);
-  hallGroup.add(hallBody, hallFlag, beads);
+  // 升级光晕（hall.glow）：一圈金色光环，复用 matDiamond，**不新增材质对象**。
+  // 静止时 visible=false（不进渲染列表 ⇒ 不占 draw call / 三角形），
+  // 只有 glow>0 时才显示并随衰减向外扩散、上升。
+  // 刻意不进 pickables、也不打 tag：拾取语义完全不变。
+  const halo = new THREE.Mesh(new THREE.TorusGeometry(1.0, 0.07, 5, 24), matDiamond);
+  halo.rotation.x = -Math.PI / 2;
+  halo.position.set(0, 1.92, 0.06);
+  halo.visible = false;
+  geos.push(halo.geometry);
+  hallGroup.add(hallBody, hallFlag, beads, halo);
   root.add(hallGroup);

@@ 新增同步函数 + update 调用
+  function syncGlow(): void {
+    const hg = hall.glow;
+    halo.visible = hg > 0.002;
+    if (halo.visible) {
+      const hs = 1.0 + (1 - hg) * 0.8;
+      halo.scale.set(hs, hs, 1);
+      halo.position.y = 1.92 + (1 - hg) * 0.7;
+    }
+  }
+
   function update(dt: number, t: number): void {
@@
     if (hall.glow > 0) { hall.glow = Math.max(0, hall.glow - dt * 1.2); }
+    syncGlow();
   }
@@
-  return { scene, sun, hall, residents, pickables, setLevel, update, pick, stats, dispose };
+  return { scene, sun, hall, residents, pickables, setLevel, update, syncGlow, pick, stats, dispose };
```

`src/app/app.ts`：

```diff
@@ case 'upgrade' → e.ok
-          this.world.hall.bounce = 1; this.world.hall.glow = 1;
+          this.world.hall.bounce = 1; this.world.hall.glow = 1; this.world.syncGlow();
@@ debugApi()
       hallBounce: () => ({ ... }),
+      /** 仅供测试：直接设置 hall.glow 并走与生产完全相同的光晕同步路径（不推进世界）。 */
+      setHallGlow: (v: number) => { app.world.hall.glow = Math.max(0, Math.min(1, v)); app.world.syncGlow(); app.render(); },
```

视觉依据（`docs/01-视觉设计说明.md`）：§5 色彩 `金 #f3c34b`、§7「升级成功 → 市政厅弹跳 + **金色光环** + 等级珠亮起」、§0 关键词「暖光」。光环复用已有的金色无光照材质 `matDiamond`（`0xffe27a`，居民可点菱形提示同款），与既有金色系一致。

### 2.3 为什么没有违反「不新增材质 / 不改 src/core」

* **不新增世界材质对象**：光环与居民提示菱形**共用同一个 `matDiamond` 实例**（只是把它的定义从居民段上移到材质段，`materials` 数组内容与顺序不变，长度仍为 **7**）。世界材质计数口径是 `world.stats().materials = materials.length`（`docs/01` §5 的 D9 口径），实测前后都是 **7**（见 §5）。
* **不改 `src/core/`**：改动只落在 `src/render/world.ts`（渲染层）与 `src/app/app.ts`（装配层）。`diff -rq src/core/` 结果：**完全一致**。
* **不改寻访/经济**：光环不进 `pickables`、不挂 tag，不参与任何拾取；升级分支只多调用一次 `syncGlow()`（纯渲染同步），不触碰 `session`/核心规则。

### 2.4 如何证明「画面上可见」（不是只断言字符串）

三层证据，全部来自实际运行：

**① 画面像素差（T12a）** —— 世界冻结 + 关闭自动 tick（整幅画面静止），只切换 `hall.glow`：

```
PASS T12a hall.glow=1 在市政厅区域（220×220）产生 729 像素画面差异；同一静止画面的对照组 glow=0↔0 仅 0 像素
      — {"diff10":729,"diff00":0,"pixels":48400,"clip":{"x":100,"y":226,"width":220,"height":220}}
```

对照组 `glow=0 ↔ glow=0` 为 **0 像素**差异（说明画面确实静止、差异不是噪声），`glow=1 ↔ glow=0` 为 **729 像素**差异，全部落在市政厅 220×220 裁剪区内。

**② 渲染器可观测属性（T12b，同一帧内原子测量）**：

```
PASS T12b 光晕只在 glow>0 时进入渲染列表（同帧原子测量）：draw calls 40→41→40，
      三角形 29172→29412→29172（+240 = 光环环面）；世界材质仍为 7
      — {"off":40,"on":41,"off2":40,"triOff":29172,"triOn":29412,"triOff2":29172,"mat":7}
```

**③ 真实触发路径（T12c）** —— 不走测试后门，而是真的攒金币 → 点升级 → 读渲染列表：

```
PASS T12c 真实升级路径点亮光晕：Lv1→Lv2，glow=1.00；同一帧 glow=1 vs glow=0 的 draw calls 42 vs 41（+1 光环）；
      衰减到 glow=0 后光环不常驻（置 1 才 41→42）
      — {"lv":[1,2],"glow":1,"onOff":{"on":42,"off":41,"glow":1},"decay":{"base":41,"up":42},"glowAfter":0}
```

> 注：T12c 的绝对值 41/42 比 T12a/T12b 的 40/41 各高 1，是因为升级后 HUD 的 toast 图层（2 个三角形的一次性 quad）仍在渲染列表里；因此 T12c 用「同一帧内 glow=1 vs glow=0」的原子差值 +1 来隔离光环贡献，而不是跟升级前基线比。详见 §8 待决问题 3。

### 2.5 截图

| 文件 | 内容 |
| --- | --- |
| `evidence/screens/14-glow-0.png` | 裁剪 220×220，`glow=0`（无光环） |
| `evidence/screens/14-glow-1.png` | 裁剪 220×220，`glow=1`（屋顶外圈金色光环） |
| `evidence/screens/14-升级光晕-glow1.png` | 全屏 390×844，**真实升级成功**后 Lv2 + 金色光环 + toast「市政厅升至 Lv.2 · 每分钟 +12.0」 |

运行环境：SwiftShader 软件渲染（非真机）。截图中 `?debug=1` 的 DEBUG ONLY 面板已由 `test/lib.mjs` 的 `shot()` 临时隐藏。

---

## 3. 任务二：居民点击区

### 3.1 复现步骤（实际命令）

复现脚本（已随证据保留）：`evidence/l3/probe-task2-resident-center.mjs`

```bash
export PATH=/mnt/ssd/apps/nodejs_v24/bin:$PATH
cd /vol1/ai/projects/wyszz-new/frontend-rebuild-hm-work-L3
node evidence/l3/probe-task2-resident-center.mjs --frames 1 --frozen 1
```

它做的事：新档 → 冻结世界 → 对每个居民调用 `residentScreen(i)`（把该居民的命中胶囊原点投影到屏幕）→ 在同一屏幕点调用 `pickAt` 与 `pickAll`（后者返回最近 6 个命中体，含标签、距离、材质是否真的被画出来 `drawn`、顶点数 `verts`）。

### 3.2 实际输出原文（改动前）

日志：`evidence/l3/probe-task2-before.log`

```
# 环境：viewport 390x844，camera={"yaw":0.6108652381980153,"pitch":0.5934119456780721,"zoom":1}，lowFx=true
# 冻结世界=true；每个采样帧之间 sleep 300ms

===== 采样帧 1/1 =====
居民#0 中心屏幕点=(266.1, 400.5)  pickAt → tag=居民 residentId=0 d=35.501  自命中=YES
        pickAll(前6) = [{"tag":"居民","d":35.501,"y":0.822,"drawn":false,"verts":54,"obj":[2.3,0.51,-0.16]},
                        {"tag":"居民","d":35.958,"y":0.575,"drawn":true,"verts":3204,...},
                        {"tag":"居民","d":36.123,"y":0.486,"drawn":true,"verts":3204,...},
                        {"tag":"浮空岛","d":37.001,"y":0.011,"drawn":true,"verts":5184,...}]
居民#1 中心屏幕点=(134.2, 352.4)  pickAt → tag=居民 residentId=1 d=37.745  自命中=YES
        pickAll(前6) = [{"tag":"居民","d":37.745,...,"drawn":false,"verts":54,...}, ...]
居民#2 中心屏幕点=(160.7, 341.6)  pickAt → tag=市政厅 residentId=-1 d=36.690  自命中=NO
        pickAll(前6) = [{"tag":"市政厅","d":36.69,"y":1.571,"drawn":false,"verts":24,"obj":[0,1.53,-0.75]},
                        {"tag":"市政厅","d":37.657,"y":1.084,"drawn":true,"verts":1908,"obj":[0,0.03,-0.85]},
                        {"tag":"居民","d":38.257,"y":0.783,"drawn":false,"verts":54,"obj":[-2.04,0.48,-1.13]},
                        {"tag":"居民","d":38.721,...,"drawn":true,"verts":3468,...}, ...]
居民#3 中心屏幕点=(224.4, 418.2)  pickAt → tag=浮空岛 residentId=-1 d=34.051  自命中=NO
        pickAll(前6) = [{"tag":"浮空岛","d":34.051,"y":1.197,"drawn":true,"verts":4704,"obj":[0,0.01,0]},
                        {"tag":"浮空岛","d":34.549,"y":0.921,"drawn":true,"verts":4704,...},
                        {"tag":"居民","d":34.723,"y":0.825,"drawn":false,"verts":54,"obj":[1.84,0.5,1.24]},
                        {"tag":"居民","d":35.176,...,"drawn":true,"verts":3348,...}, ...]

汇总：自命中 2/4
```

复现成功：**默认视角下 4 个居民有 2 个中心点不自命中**，与任务书现状描述一致。

> 上面对 `pickAll` 的 JSON 做了**省略（`...`）以便阅读**；逐字符的完整原文在 `evidence/l3/probe-task2-before.log`（关键字段 `tag / d / drawn / verts` 均未改写，被折叠的只是中间字段）。

### 3.3 原因分析（两类，互不相同）

先说一个**被推翻的前提**：任务书的侦察笔记写「居民本体网格不在 `pickables` 里，只有胶囊可拾取」——**实测不成立**。`src/render/world.ts:251` 的 `meshOf(residentGeometry(pal), matFlat, RESIDENT_TAG, true, false)` 用的是 `meshOf` 的默认 `pickable = true`，所以**居民本体也是可拾取物**（上面 `verts=3204~3468, drawn=true` 的命中就是本体）。胶囊（`verts=54`、`drawn=false`）只是离相机最近的那个。

**原因 A · 隐形辅助命中体抢点击（居民#2，可修）**
最近命中是 `{"tag":"市政厅","d":36.69,"drawn":false,"verts":24}`：`verts=24` 正是 `BoxGeometry` 的顶点数，即 `src/render/world.ts:222` 那个**不可见**的市政厅命中盒 `BoxGeometry(w+1.8, 3.0, d+1.0)`；而市政厅可见外形只有 `w=1.7 × d=1.25`（`src/render/layout.ts`），命中盒在 x 方向宽 3.5、z 方向深 2.25，**比可见建筑大一圈**，覆盖到广场上。射线穿过居民#2 胶囊原点时，先在 `d=36.69` 打中这个隐形盒，再在 `d=38.257` 打中居民自己的胶囊；`pick()` 取 `hits[0]`（最近），于是把点击判给了市政厅。玩家看到的是"居民没被建筑挡住，却点不到"。

**原因 B · 可见几何真实遮挡（居民#3，不是缺陷）**
最近命中是 `{"tag":"浮空岛","d":34.051,"drawn":true,"verts":4704}` —— 一个**真的被画出来**的岛面/景物网格（`y=1.197`，位于相机与居民之间），居民胶囊在 `d=34.723`。这是**真实的视觉遮挡**：画面上居民确实被这块几何挡住，按最近者胜返回它才是正确的。`docs/03-浏览器测试报告.md` §已知局限 把它记为「遮挡的真实表现，不是拾取错误」，本次实测支持该结论。

→ 因此**只修原因 A**：让隐形辅助命中体不再抢走居民的点击；可见几何的遮挡语义原样保留。

### 3.4 改动（diff，`src/render/world.ts` 的 `pick()`）

```diff
+  /** 该命中体的材质是否真的被画出来（隐形辅助命中体：市政厅大盒、居民胶囊）。 */
+  function isDrawnHit(o: THREE.Object3D): boolean {
+    const m = (o as THREE.Mesh).material as THREE.Material | THREE.Material[] | undefined;
+    if (!m) { return true; }
+    return Array.isArray(m) ? m.every(x => x.visible !== false) : m.visible !== false;
+  }
+
   function pick(raycaster: THREE.Raycaster): PickResult {
     root.updateMatrixWorld(true);
     const hits = raycaster.intersectObjects(pickables, false);
     if (hits.length === 0) { return { tag: '', object: null, point: null, distance: Infinity, residentId: -1 }; }
-    const h = hits[0];
+    // 居民点击区修复：最近的命中若是**隐形辅助命中体**（市政厅那个比可见外形大一圈的盒），
+    // 而它后面确实还命中了居民（隐形胶囊或本体），则判给居民——隐形辅助体只是兜底命中区，
+    // 不该抢走居民的点击。**可见**几何仍按最近者胜 ⇒「隔着建筑点不到」的语义完全不变。
+    let h = hits[0];
+    if (!isDrawnHit(h.object) && resolveTag(h.object) !== RESIDENT_TAG) {
+      const r = hits.find(x => resolveTag(x.object) === RESIDENT_TAG);
+      if (r) { h = r; }
+    }
```

规则只有一条：**当且仅当**最近的命中体是"不可见且非居民"的辅助体、且它后面确实还命中了居民（胶囊或本体）时，改判给那个居民。其余一切情况（最近命中是可见几何、最近命中本身就是居民、什么都没打中）行为与改动前**逐字节相同**。

### 3.5 改动后的实测（同一探针）

日志：`evidence/l3/probe-task2-after.log`（3 帧，冻结）

```
居民#2 中心屏幕点=(160.7, 341.6)  pickAt → tag=居民 residentId=2 d=38.250  自命中=YES
        pickAll(前6) = [{"tag":"市政厅","d":36.69,...,"drawn":false,"verts":24},   ← 隐形盒仍在最近处
                        {"tag":"市政厅","d":37.657,...,"drawn":true,"verts":1908},
                        {"tag":"居民","d":38.25,...,"drawn":false,"verts":54}, ...]  ← 改判给居民
居民#3 中心屏幕点=(224.4, 418.1)  pickAt → tag=浮空岛 residentId=-1 d=34.055  自命中=NO   ← 可见遮挡语义保留
汇总：自命中 9/12（每帧 3/4）
```

世界不冻结、连续 6 帧采样（日志 `evidence/l3/probe-task2-running.log`）：每帧都是 **3/4**，居民#3 始终被可见几何挡住。

### 3.6 为什么没有改变寻访规则、金币与声望数值

* 改动只在 `pick()` 的"选哪一个命中体"这一步，**不碰** `src/core/visit.ts`、`src/core/economy.ts`、`src/game/session.ts`、也不碰 `applyResidentVisit` / `applyUpgrade` 的任何分支。
* 判定结果仍然是"命中/未命中某个标签"，`session.tap(tag)` 的入参与之前完全同构：改成居民后走的就是原本的"点居民 +3 金币 / +1 声望 +1 寻访"路径，没有任何新的奖励分支或倍率。
* 回归佐证：R2 中 `T04a`（金币 +3、声望 +1/+1、寻访 +1）、`T09a`（30 点扫描：居民点击恰好 +1 寻访、非居民点击存档字节不变）、`T13b`（435+439 个"隔着可见几何"的点 0 泄漏）全部通过。

---

## 4. 三次全量回归结果表（R0 / R1 / R2）

每步完整原始输出（10 份日志 + `summary.json`）：

| 轮次 | 含义 | 日志目录 |
| --- | --- | --- |
| **R0** | 改动前基线（任务一前，也等于任务二前） | `evidence/regress-20261012-033523/` |
| **R1** | 任务一改动后（同时作为任务二的"改动前"基线） | `evidence/regress-20261012-034436/` |
| **R2** | 任务二改动后（最终状态） | `evidence/regress-20261012-035553/` |

| # | 步骤 | R0 耗时/结果/样例 | R1 耗时/结果/样例 | R2 耗时/结果/样例 |
| --- | --- | --- | --- | --- |
| 1 | 类型检查 | 0.3s PASS | 0.3s PASS | 0.3s PASS |
| 2 | 构建(core+web+wechat) | 0.7s PASS · web 614.0KiB / wechat 614.0KiB | 0.7s PASS · web 615.4KiB / wechat 615.4KiB | 0.7s PASS · web 615.9KiB / wechat 615.9KiB |
| 3 | 契约样例(fixtures) | 0.2s PASS · **32/32** | 0.2s PASS · **32/32** | 0.2s PASS · **32/32** |
| 4 | 会话回放(replay) | 0.2s PASS · **32/32** | 0.2s PASS · **32/32** | 0.2s PASS · **32/32** |
| 5 | 玩法(gameplay) | 17.3s PASS · **21/21** | 16.2s PASS · **21/21** | 23.0s PASS · **24/24**（+3 新增） |
| 6 | UI(ui) | 15.0s PASS · **23/23** | 14.3s PASS · **23/23** | 14.2s PASS · **23/23** |
| 7 | 视觉(visual) | 28.8s PASS · **12/12** | 28.2s PASS · **12/12** | 39.1s PASS · **16/16**（+4 新增） |
| 8 | 浏览器测试(全量) | 66.0s PASS · **59/59** | 66.3s PASS · **59/59** | 83.5s PASS · **66/66**（+7 新增） |
| 9 | 微信替身测试 | 60.7s PASS · **37/37** | 52.2s PASS · **37/37** | 63.0s PASS · **37/37** |
| 10 | 隔离检查(项目专用) | 0.2s PASS · 0 违规 / 93 白名单 | 0.2s PASS · 0 违规 / 93 白名单 | 0.2s PASS · 0 违规 / 93 白名单 |
| — | **总耗时 / 结论** | **189.4s / PASS** | **178.7s / PASS** | **224.2s / PASS** |

**样例数合计：R0 = 216，R1 = 216，R2 = 230。样例数只增不减**（新增 7：T12a–T12d + T13a–T13c），原有断言**一条未删、一条未改**。

原有断言在 R2 中的抽样复核（全部 PASS，仅数字变化）：

```
PASS T01d 渲染预算：41 draw calls，29174 三角形，10 programs，7 材质（SwiftShader lowFx=true）
PASS T04e 点市政厅（真实3D射线）升级成功 Lv1→Lv2，扣费 20 — {"b":21291,"a":1306}
PASS T04f 升级反馈：市政厅弹跳/发光、速率提升 — {"bounce":0.64,"shake":0,"glow":0.76}
PASS T05b 旋转后射线拾取：2/4 居民中心命中自身（其余被遮挡）；真实点击一个居民成功=#1 — 居民,居民,浮空岛,居民
PASS T09a 30 点真实鼠标点击扫描：30/30 与射线标签、状态变化一致 — {"居民":6,"市政厅":4,"道路":6,"浮空岛":6,"树":3,"云":2,"(空/天空)":3}
PASS T10-390x844 视口 390×844：市政厅在自由区（84–771），4/4 居民在自由区、3 个居民中心可被射线命中
```

> 说明：`T05b` 是旋转后的采样（2/4~3/4 随机，取决于当时居民走到哪里），断言是 `okp >= 1 && rr >= 0`，本来就不是"必须 4/4"；`T10-*` 的断言是 `pickable >= 2`，修复后从 2 升到 3，仍然通过。

---

## 5. 预算前后对比（上限：draw calls 60 / 三角形 40000 / programs 16 / 世界材质 7）

数据来源：`evidence/perf.json`（T11a 写入）+ T01d 行。

| 指标 | R0 改动前 | R2 改动后（glow=0，静止） | R2 光晕点亮时（glow=1） | 上限 | 结论 |
| --- | --- | --- | --- | --- | --- |
| draw calls（世界+HUD） | **40** | **40** | **41**（+1 光环） | ≤ 60 | ✅ 通过 |
| 三角形（世界+HUD） | **29172** | **29172** | **29412**（+240 光环环面） | ≤ 40000 | ✅ 通过 |
| programs | **10** | **10** | **10** | ≤ 16 | ✅ 通过 |
| 世界材质对象数 | **7** | **7** | **7** | ≤ 7 | ✅ 通过（未新增） |
| 纹理（`memory.textures`） | 15 | 15 | 15 | （文档口径 15） | 不变 |
| `world.stats()` 三角形 | 22652 | **22892**（+240） | 22892 | — | 见下方说明 |
| `world.stats()` 网格数 | 31 | **32**（+1） | 32 | — | 见下方说明 |
| SwiftShader 帧率（仅可运行性参考） | 26.2 fps | 26.0 / 26.7 fps | — | — | 非真机性能 |

**说明（口径差异，如实记录）**：`world.stats()` 遍历场景时只判断 `material.visible !== false`，**不看 `mesh.visible`**，所以那个静止时隐藏的光环仍被它计入（+1 网格 / +240 三角形）。而 `renderer.info.render` 反映真实绘制，静止时**完全没有增加**（29172 不变）。我**没有**去改 `stats()` 的口径——那会动到已有的 T11a 断言与 D9 已统一的"世界材质 7"口径。这也是为什么上表把两者分开列。

> 另注：`T01d` 读到 41 draw calls / 29174 三角形（比 T11a 高 1 call / 2 三角形），这是**改动前就存在**的现象——采样瞬间有飘字/粒子等特效在播（2 个三角形的 sprite）。R0 与 R2 的 T01d 数值相同（41/29174），不是本次改动引入。

---

## 6. 新增测试清单与实际输出

只增不删：`test/` 下只修改了 **2 个已有文件**，且都是**纯追加**（`diff -u` 中删除行 = 0，只有 diff 头）：

| 文件 | 追加行数 | 追加位置 |
| --- | --- | --- |
| `test/t-gameplay.mjs` | **+51**（0 删除） | `run()` 末尾、原 `T05h` 与 `pg._ctx.close()` 之后 |
| `test/t-visual.mjs` | **+66**（0 删除） | `run()` 末尾、T10 视口循环之后 |

新增样例 **7 个**（浏览器全量 59 → 66）：

| 样例 | 断言（摘要） |
| --- | --- |
| `T12a` | `glow=1` 与 `glow=0` 在市政厅 220×220 区域内**像素差异 > 200**，且同画面 `glow=0↔0` 差异 ≤ 10 |
| `T12b` | 同一帧内 `glow=0→1→0`：draw calls +1、三角形 +240、材质仍为 7 |
| `T12c` | **真实升级路径**（攒金币 → 升级成功）后 `glow>0`，光环进入渲染列表（+1 call）；衰减到 0 后光环不常驻 |
| `T12d` | T12 无 pageerror |
| `T13a` | **正例**：居民中心点自命中最好一帧 ≥ 3/4（基线 2/4）；"最近命中是隐形辅助命中体"的样本**全部**判给该居民 |
| `T13b` | **负例**：居民中心 ±30px 窗口内"最近命中是**可见**非居民、其后仍有居民"的点**全部不得判给居民**（0 泄漏）；被可见几何遮挡的居民中心仍判给可见物体 |
| `T13c` | T13 无 pageerror |

R2 中的实际输出：

```
PASS T12a hall.glow=1 在市政厅区域（220×220）产生 729 像素画面差异；同一静止画面的对照组 glow=0↔0 仅 0 像素
      — {"diff10":729,"diff00":0,"pixels":48400,"clip":{"x":100,"y":226,"width":220,"height":220}}
PASS T12b 光晕只在 glow>0 时进入渲染列表（同帧原子测量）：draw calls 40→41→40，三角形 29172→29412→29172（+240 = 光环环面）；世界材质仍为 7
      — {"off":40,"on":41,"off2":40,"triOff":29172,"triOn":29412,"triOff2":29172,"mat":7}
PASS T12c 真实升级路径点亮光晕：Lv1→Lv2，glow=1.00；同一帧 glow=1 vs glow=0 的 draw calls 42 vs 41（+1 光环）；衰减到 glow=0 后光环不常驻（置 1 才 41→42）
      — {"lv":[1,2],"glow":1,"onOff":{"on":42,"off":41,"glow":1},"decay":{"base":41,"up":42},"glowAfter":0}
PASS T12d T12 无 pageerror
PASS T13a 居民中心点自命中最好一帧 3/4（修复前基线 2/4）；其中"最近命中是隐形辅助命中体（市政厅大盒 verts=24）"的 6/6 例全部判给该居民
      — {"selfByFrame":[3,3,3,3,3,3],"invBlocked":[{"i":2,"firstTag":"市政厅","verts":24}, …×6]}
PASS T13b 负例·隔着可见几何仍点不到：居民中心 ±30px 窗口内"最近命中是可见非居民、其后仍有居民"的 435 个点 0 泄漏；可见遮挡的居民中心 6/6 例仍判给可见物体
      — {"winDrawn":435,"winLeak":0,"visBlocked":[{"i":3,"firstTag":"浮空岛"}, …×6]}
PASS T13c T13 无 pageerror
```

---

## 7. 截图（全部来自本次实际运行）

运行环境统一为：**chromium + ANGLE/SwiftShader 软件渲染（`lowFx=true`，`pixelRatio=1`），视口 390×844，不是真机、不是真 GPU**。

| 路径 | 内容 |
| --- | --- |
| `evidence/screens/14-glow-0.png` | 市政厅区域 220×220，`glow=0` |
| `evidence/screens/14-glow-1.png` | 市政厅区域 220×220，`glow=1`（金色光环） |
| `evidence/screens/14-升级光晕-glow1.png` | 全屏：真实升级到 Lv2 后的金色光环 + toast |
| `evidence/screens/12-射线命中标注.png`、`12-射线扫描底图.png` | R2 的 T09 扫描图（含本次拾取规则） |
| `evidence/screens/13-视口-*.png`（6 张） | R2 的 T10 多视口（居民中心可命中数 2 → 3） |

探针脚本与原始日志（可复跑）：

| 路径 | 内容 |
| --- | --- |
| `evidence/l3/probe-task2-resident-center.mjs` | 任务二复现探针（居民中心 → pickAt/pickAll） |
| `evidence/l3/probe-task2-before.log` | **改动前**原始输出（自命中 2/4） |
| `evidence/l3/probe-task2-after.log` | 改动后（冻结，3/4） |
| `evidence/l3/probe-task2-running.log` | 改动后（世界运行，连续 6 帧，每帧 3/4） |
| `evidence/l3/probe-task2-window-scan.mjs` | 负例用的窗口扫描探针 |
| `evidence/l3/probe-task1-glow-pixels.mjs` | 任务一像素差探针 |

---

## 8. 待决问题

1. **居民#3 的中心点仍然不自命中（被可见地形/建筑真实遮挡）。**
   这是任务书要求保留的语义（负例），我没有改。如果产品要求"隔着建筑也要能点到居民"，那就必须改拾取优先级语义（例如居民整体优先于任何非居民命中体），这会连带影响"点建筑/地形"的判定，**超出 L3 授权**，需要 Lead/产品裁决。
2. **`world.stats()` 的网格/三角形计数包含隐藏对象。**
   光环静止时隐藏，`renderer.info` 不计它，但 `world.stats()` 会 +1 网格 / +240 三角形。为了让 `stats()` 口径与渲染器一致需要改 `stats()`（渲染层），但会动到 T11a 打印的既有口径与 `docs/01` §5/§9 的 D9 记录，故**未改**，只在 §5 里如实分开列。
3. **升级后 HUD 的 toast 图层会在 fx 结束后继续占用 1 个 draw call 若干秒。**
   T12c 因此改用"同一帧内 glow=1 vs glow=0"的原子差值，而不是与升级前基线比。我**没有**去深究 toast 图层为何比它的 `toastLife`（3s）存活更久（可能与 `hud.update` 的时序/多次 toast 有关），也没有改动 HUD —— 它与本任务两项改动无关，属于既有行为。
4. **调试接口 `pickAll` 的输出结构被追加了字段**（`drawn` / `verts` / `obj`）。
   这是纯追加、只读诊断，`test/` 下原本没有任何用例使用 `pickAll`；但如果有仓库外的工具依赖旧字段结构，需要知会。
5. **纹理数 15（浏览器）/ 8（微信）的口径差异**（`docs/01` §9 已列的既有待决）本次未涉及，未做任何调查。

---

## 9. 诚实记录（没做到的、不确定的、偏离字面的）

1. **我新增了 2 个调试接口，严格说超出了"最小改动"的字面**：`world.syncGlow()` 与 `debugApi().setHallGlow(v)`（仅 `?debug=1` 存在）。理由：要让"`hall.glow` 状态 → 画面差异"可重复测量，必须能在不推进世界的前提下切换该状态；否则居民走动/云飘/岛浮动会污染像素比对（我最初的实现直接调 `world.update(0, app.time)`，结果两次 `glow=0` 截图差 6641 像素——这个坑已在探针 v3 中定位并修掉，改为只同步光晕）。`setHallGlow` 走的是与生产**完全相同**的 `syncGlow()` 路径，且另有 T12c 用**真实升级路径**交叉验证。
2. **升级成功分支多了一行 `this.world.syncGlow()`**。生产上它只让光晕提前 1 帧出现（原本由下一帧 `update()` 同步），没有行为风险；但它确实是为让 T12c 在世界冻结时也能观测而加的，如实说明。
3. **任务书侦察笔记的一处前提被实测推翻**：「居民本体网格不在 `pickables` 里，只有胶囊可拾取」——居民本体（`verts≈3204~3468`）也在 `pickables` 里。这不影响修复方案，但原因分析必须以此为准（§3.3）。
4. **`docs/01-视觉设计说明.md` §8 写"隐形碰撞胶囊（半径 0.42）"，实测实现是 0.55**（`CapsuleGeometry(0.55, 0.5)`，`src/render/world.ts:253`）。这是文档与实现的既有差异（`docs/03` 附录 A 已登记），我**没有**改动它。
5. **我没有真机、没有真 GPU**。所有截图、draw call / 三角形 / programs / 帧率都来自 SwiftShader 软件渲染；帧率（26 fps 左右）**不能**当作真机性能结论。
6. **像素差异 729 像素是"市政厅区域 220×220 裁剪"内的计数**，不是全屏计数（HUD 与画面其它区域不受光晕影响）。裁剪区是 `hallScreen()` 投影点 ±110px，脚本里写死并可复算。
7. **`T12c` 的 draw call 绝对值（41/42）与 T12a/T12b（40/41）不一致**，原因见 §8 第 3 条；断言用的是同帧差值 +1，不是绝对值。
8. **R1/R2 的 visual 步骤变慢**（28.2s → 39.1s）与 gameplay（16.2s → 23.0s）来自新增用例（含 5s 静止等待、截图、像素比对、484×2 次射线扫描），不是代码变慢。
9. **任务二只达成了"部分修复"**：默认视角自命中从 2/4 提到 3/4，**不是 4/4**，且我不打算把它做到 4/4（那会破坏"隔着可见建筑点不到"的语义，也正是任务书要求保留的负例）。
10. 我没有运行过 `npm run test:public`（公网预览检查，全量回归按设计不包含它），也没有跑真机/官方模拟器验收手册里的任何步骤。
11. **原始只读目录未被改动**：`diff -rq` 后仅 4 个文件不同（即上表 4 个），`src/core/` 完全一致；原目录 `src/`、`test/` 下没有任何文件在本次会话时间窗内被写过（`find -newermt` 为空）。
12. 本次没有产生任何回退（R0/R1/R2 全绿），因此报告中没有"已回退"的条目。

---

## 附录 A · 本次改动的校验和（SHA256）

见 §附录 A 由 `sha256sum` 现场生成，命令与输出：

```bash
cd /vol1/ai/projects/wyszz-new/frontend-rebuild-hm-work-L3
sha256sum src/render/world.ts src/app/app.ts test/t-visual.mjs test/t-gameplay.mjs docs/19-L3-报告.md
```

（实际输出见本报告末尾追加的「SHA256 现场输出」小节。）

### SHA256 现场输出

```
8a3fae38454f9fcf1ef6be7f507f9b1cbfa1caa006e1e674d55ea7ea1d8061a6  src/render/world.ts
494461f078653f528dc8fd7a223039613ee6004c7ea6bbff81566bdd87d4a8ba  src/app/app.ts
ba7dfb387a0bef9272f51fa24c0320ea9a294f12bb9e1c2251910ca52547f238  test/t-visual.mjs
0ef60a0b31c8446744678b0d133ce3946f0a3f36e6f0cc7c64e13a6c81e64121  test/t-gameplay.mjs
```

（本报告自身的 SHA256 在交付消息中给出，避免自指导致校验和随内容变化。）
