# S-25「岛屿形状与连接改造」· 截图与性能读数报告

> 执行人：S3 `island-e2e`（只写测试与工具，未改任何 `src/render/**`）
> 交付日期：2026-10-22（北京时间）
> 目标树：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm035-island`（内部包 `dist/web-internal`，version 0.3.3）
> 基线树：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm033`（0.3.3 基线，**dist 已存在，未重新构建**）

---

## 1. 测试文件与运行方式

| 文件 | 作用 |
| --- | --- |
| `test/t-island.mjs` | 浏览器端到端验收（截图 / 买地连接带 / pageerror / 三角面与 draw call 读数 / 岛底像素与几何读数 / 动画时序） |
| `tools/test-island-png.mjs` | 零依赖 PNG 解码与图像分析工具（解码 / 掩码计数 / bbox / 下缘轮廓 / 竖直连续段 / 连通块 / 像素差 / 振荡检测） |
| `tools/test-island-e2e.mjs` | Node 侧 runner：跑当前树（after）+ 基线树（before），并把两份读数并成对比表、把 before 段并进 `island-readings.json` |

```bash
export PATH=/mnt/ssd/apps/nodejs_v24/bin:$PATH
cd /vol1/ai/projects/wyszz-new/frontend-rebuild-hm035-island

# 单跑当前树（after）
node test/t-island.mjs

# 基线树（before，只读它的 dist，不构建它）
T_ISLAND_TREE=/vol1/ai/projects/wyszz-new/frontend-rebuild-hm033 T_ISLAND_PREFIX=before- node test/t-island.mjs

# 一键跑 before + after 并出对比表
node tools/test-island-e2e.mjs --all
#   --build 参数会先执行 node tools/build-web.mjs --internal
```

环境变量：`T_ISLAND_TREE`（被测树根，默认当前树）、`T_ISLAND_PREFIX`（截图/读数文件名前缀，默认无）、`T_ISLAND_OUT`（输出目录，默认 `tasks-out/S-25/evidence`）。
测试自带 `serve()` + 系统 chromium（`/usr/bin/chromium`），不新增依赖、不联网。

---

## 2. 截图清单（20 张主图 + 9 张辅助图）

目录：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm/tasks-out/S-25/evidence/`

**主图（5 屏 × 4 视角 = 20 张）**，命名 `island-<宽>x<高>-<视角>.png`：

| 屏幕 | default(34°) | top(88°) | low(16°) | under(−20°) |
| --- | --- | --- | --- | --- |
| 320×568 | `island-320x568-default.png` | `island-320x568-top.png` | `island-320x568-low.png` | `island-320x568-under.png` |
| 360×640 | `island-360x640-default.png` | `island-360x640-top.png` | `island-360x640-low.png` | `island-360x640-under.png` |
| 390×844 | `island-390x844-default.png` | `island-390x844-top.png` | `island-390x844-low.png` | `island-390x844-under.png` |
| 414×896 | `island-414x896-default.png` | `island-414x896-top.png` | `island-414x896-low.png` | `island-414x896-under.png` |
| 430×932 | `island-430x932-default.png` | `island-430x932-top.png` | `island-430x932-low.png` | `island-430x932-under.png` |

基线树同款 20 张：`before-island-320x568-default.png` … `before-island-430x932-under.png`（前缀 `before-`）。

**辅助图**：买地前后同机位对照 `island-buy-before-390x844.png` / `island-buy-after-390x844.png`；水晶几何采样 `island-390x844-under-crystal.png`；升起动画第 6/7/8 帧 `island-rise-frame-6/7/8.png`；落位后稳定性连拍 `island-stability-under-0/1/2.png`（基线同款加 `before-` 前缀）。

**读数文件**：`island-readings.json`（after，含 `sections.before` 基线段）、`island-readings-before.json`（基线）、`island-compare.json`（before/after 对比表）。三份均已瘦身到 **30–34 KB**（早前版本把解码后的像素数组写进去了，已剔除）。

---

## 3. pageerror 计数

**pageerror = 0**（after 与 before 两轮、全部 5 个页面尺寸、共 30+ 次导航，均无未捕获异常）。
判据 `ISL-G1`：五屏截图 + 买地流程 + 岛底探针 + 稳定性连拍全程累计，pageerror 必须为 0。

---

## 4. 关键读数（before 0.3.3 基线 → after 本次改造）

| 项目 | before（0.3.3） | after（改造后） | 判读 |
| --- | --- | --- | --- |
| 启动 triangles | 46161 | 43465 | ✅ 降了 2696（去掉岩锥、换成六棱台） |
| 启动 draw calls | 45 | 44 | ✅ 未增加 |
| programs | 11 | 11 | ✅ 未增加 |
| materials | 19 | 19 | ✅ **未增加**（基线 19，硬性要求） |
| geometries | 35 | 35 | ✅ 未增加 |
| 买地后 triangles Δ | −5219 | −5297 | ✅ 买一块不再暴涨 |
| 买地后 scene triangles Δ | +664 | +646 | ✅ |
| 买地后 draw calls | 47 | 47 | ✅ ≤ 80 |
| 渲染预算上限 | triangles ≤ 60000、calls ≤ 80、programs ≤ 16、materials ≤ 19 | 全部满足 ✅ |
| 落位后 3 次连续采样 | 41779/47 → 41779/47 → 41779/47 | 41689/47 ×3 完全一致 ✅ 不闪 |
| 地块层重建次数（落位后隔 20 帧 ×3） | 5 → 5 → 5 | 5 → 5 → 5 ✅ 不重复抖动 |
| 升起落位帧数 | 第 18 帧（0.300 s） | 第 18 帧（0.300 s） ✅ 目标 0.3–0.4 s |
| 动画期振荡像素（6≠7 且 7≠8 但 6=8） | 62 | 68 | ✅ 远小于同期运动量（1500+ px），无闪烁/z-fighting |

---

## 5. 连接带硬读数（买地前后同一机位、同一接缝）

买的是 **与已拥有地块恰好只有一个公共邻居的候选地 (0,2)**；接缝中点 = 新地块与其父地块屏幕坐标的中点。
相机先 `setCamera(yaw=35°, pitch=34°, zoom=1)` 并**等距离完全收敛**（`settleCamera`：连续两次 `frameRadius().dist` 差 < 1e-4），买地后用 `zoom = fitGoal / dist_before` **把相机钉回同一距离**（买地会改变 `fitRadius`），因此前后两张图是严格同机位。

| 读数 | before | after |
| --- | --- | --- |
| 接缝 33×33 邻域变化像素（Σ\|Δ\|>12） | 971 | 914 |
| 接缝 **11×11** 紧邻变化像素 | — | **121**（变化确实集中在接缝上，不是全岛位移） |
| 最大通道差 | 392 | 391 |
| 接缝 21×21「岩/草沿」像素 | 0 → 0 | 213 → 93（基线口径下也是 0，见下方口径说明） |
| 接缝亮度 | 119.6 → 157.6 | 120.6 → 156.7 |
| 纯黑(RGB≤30)最大连通块 | — | 0 px ✅ 不是黑洞 |
| 接缝邻域天空像素（买地后） | — | 0 px ✅ 没开天窗 |
| 买地前后相机距离 | 63.258 → 63.257（相对差 0.002 %） | 同左 ✅ 严格同机位 |
| 接缝屏幕位移 | — | 0,−1 px |
| 天空角落对照区变化 | — | 0 px（自由区变化 56661 px）✅ 变化集中在岛上 |

**口径说明**：接缝那一小块在 default(34°) 视角下**看不到紫色岩**——因为新地块与父地块顶面之间是 `Band.Seam`（草沿色 0x51a51f），而**岩桥挂在两地块之间的竖直壁面上**，从上方看被两块顶面挡住。因此「接缝处必须出现岩紫像素」这个旧判据在 default 视角不成立（Lead 已确认）。现行判据是：
1. 接缝邻域像素变化 ≥ 200（实测 914）且紧邻 11×11 内 ≥ 40（实测 121）⇒ 连接带确实长出来了；
2. 接缝邻域**纯黑连通块 ≤ 12**（实测 0）⇒ 不是黑洞；
3. 接缝邻域**天空像素 = 0**（实测 0）⇒ 没开天窗；
4. 接缝 21×21「岩/草沿」像素 after > before（岩桥/草沿确实占住了接缝）。

---

## 6. 岛底（under −20°）像素与几何读数

像素侧（390×844，从「草沿下边缘」逐列向下扫，遇到天空亮像素即停 ⇒ 量到的就是贴着岛顶轮廓下方那块实体，不会被远处的云带偏，也不会把 HUD 金色按钮算进来）：

| 读数 | before（岩锥） | after（六棱台平底） |
| --- | --- | --- |
| 岛底实体像素 | 321（岩锥可见面） | **2067–2499 px**（平底可见面积 ≈ 7–8 倍） |
| 岛底最大厚度 | 44 px | 90 px（上限为扫描窗口） |
| 岛底平均亮度 | 48.2 | 123.4 |
| 岛底近黑(L<42) 占比 | 39.2 % | 15.2 % |
| 岛底紫色岩层像素 / meanL | 3098 px / 48.2 | 340 px / 52.0 |
| 岛底主色 | (58,45,69) | (54,36,42) |
| 水晶像素（under 视角） | 307 | 105（亮度均值 198.7 ⇒ 用的是无光照材质 `matGlow`，不会发黑） |
| 水晶像素（default 34°） | 107 ⇒ **从侧面穿出** | **0** ✅ 不再穿帮 |
| 水晶像素（top 88°） | 0 | 0 ✅ |
| 水晶像素（low 16°） | 210 | 12（16° 本就能看到岛底下方，给 ≤15 宽限，只记录不判定） |

几何侧（**结构读数**，`pickAt` 拿命中点的世界坐标，不依赖颜色）：

| 读数 | before | after | 判据 |
| --- | --- | --- | --- |
| 底面平面上的采样点（y=−1.75±0.02） | 0（y 铺开在尖锥上） | **120 / 160** | ≥ 10 ✅ |
| 该平面内 y 起伏 | — | **0.0141** | ≤ 0.02 ✅ |
| 采样点到最近地块中心的水平距离 | — | **最大 1.087** | ≤ 1.24+0.05 ✅ |
| 水晶命中点 y 范围 | −2.062 .. −3.46 | **−2.26 .. −1.72** | 须全在 −1.75 以下 ⚠ 见问题 ① |
| 水晶到最近地块中心距离 | 0.407 | 0.639 | ≤ 1.24 ✅ 不戳出底面圆盘 |
| 下缘最平段宽度占比（口径B，before/after 对照） | — | 26.6 % | 须 after ≥ before（基线读数需用同一份 test 重跑基线树才能填上） |

**结论**：底面**几何上确实是平的**（y 恒 −1.75±0.014、都在各自地块底面圆盘 r=1.24 内），不是岩锥；
但**底面着色偏暗**（主色 (54,36,42)，L≈42）——见问题 ②。

---

## 7. 动画时序读数

- `RISE_TIME = 0.3 s`，逐帧 age 序列 0.017 → 0.033 → 0.050 → 0.067 → 0.083 → 0.100 …
- rise 出现 → **第 18 帧（0.300 s）落位**，落在任务要求的 0.3–0.4 s 区间内。
- 落位后 `smoke.rise = null`、烟雾 `active = 0`（已回收）。
- 落位后连续 3 次 `info()`：triangles/calls **完全一致**（不闪）。
- 落位后隔 20 帧连采 3 次 `landRebuilds()`：**5 → 5 → 5**（不重复重建、不重复抖动）。
- 冻结世界后 under 视角连拍 3 张，岛体区域 [97,426]–[298,561] 内 **1↔2 帧变化 0 px、2↔3 帧变化 0 px** ⇒ 岛底/水晶不闪。
- 升起动画第 6/7/8 帧的**振荡像素**（6≠7 且 7≠8 但 6=8）= 68，远小于同期运动量（1500+ px）⇒ 无 z-fighting 抖动（0.3.3 基线本身有 62 px 的既有阴影微抖，属同量级）。

---

## 8. 发现的问题（**只报告，不改产品代码**；下列片段可直接套用）

### ① 水晶顶端有约 0.03 高度戳进底面（唯一残留的几何越界）

**现象**：`pickAt` 采到的水晶表面最高点 y ≈ **−1.72**，而底面平面在 y = **−1.75** ⇒ 水晶八面体有一个角**高于底面 0.03**，即「穿底面」了 3 cm。
**根因**：`src/render/hexworld.ts` `buildCrystalsGeometry()` 里 `cy = BOTTOM_Y - gap - h/2`，`gap = 0.05 + hash(q,r,4)*0.10`，但八面体是**带倾角**摆放的（`b.add(P.oct, …, 0, 0.4, 0, …)`），倾斜后最高角比「轴向顶��」高出约 0.085，抵消掉了 `gap` 的余量。

**建议改法（改 `src/render/hexworld.ts` 的 `buildCrystalsGeometry`，把 gap 下限抬到 0.14 即可，仍在底面下沿的观感范围内）**：

```ts
// src/render/hexworld.ts · buildCrystalsGeometry()
const gap = 0.14 + hash(q, r, 4) * 0.08;   // 原 0.05 + hash*0.10：倾斜后的角会戳进底面 0.03
```
或把八面体的倾角从 0.4 降到 ≤ 0.15（保持 `gap` 不变）：
```ts
b.add(P.oct, C.crystalA, tx, cy, tz, 0, 0.15, 0, 0.2 * sc, h / 2, 0.2 * sc, { flat: true });
```
（两种改法任选其一即可让 `maxWy ≤ −1.75`。）

### ② 岛底虽然「有颜色」，但朝下的面只吃到半球光的地面色 ⇒ 偏暗

**现象**：底面主色渲染成 **(54,36,42)、L≈42**；对比 0.3.3 岩锥底 (58,45,69)、L≈48。
**根因**：`src/render/world.ts` 里 `matFlat/matLit` 是 `MeshLambertMaterial`，底面法线朝下 ⇒ 平行光（sun）贡献 0，只剩 `HemisphereLight(0xbfe0ff, 0x9a7a58, 1.15)` 的**地面色**（再除以 π）⇒ 天然偏暗。调色板改亮只能补偿一部分（albedo ≤ 1）。

**建议改法 A（推荐，不新增材质、不改 draw call/programs）** —— 在 `src/render/world.ts` 的灯光段加一盏极弱的**底部补光**：

```ts
// src/render/world.ts · 紧跟 scene.add(new THREE.HemisphereLight(...)) 之后
// 岛底（六棱台底面 y=-1.75，法线朝下）只吃得到半球光的地面色 → 偏暗；补一盏朝上的弱光。
const bottomFill = new THREE.DirectionalLight(0xbfd8ff, 0.55);
bottomFill.position.set(0, -1, 0.35);   // 朝上照：法线朝下的面才吃得到
scene.add(bottomFill);
```
> 说明：新增一盏平行光**不新增材质、不新增 draw call**；`programs` 仍是 11（只是灯光计数变了，着色器配置数不变），`materials` 仍 19，满足任务硬约束。

**建议改法 B（只改调色板/着色，最小侵入）** —— 在 `src/render/hexworld.ts` 的 `bandColor()` 里给朝下的底面换成更亮的岩色并把 shade 顶到 1：

```ts
case Band.RockB:
  if (ny < -0.6) { return { color: C.sandLight, shade: 1.0 }; }  // 朝下的底面：亮砂岩色，避免发黑
```
> 但这只把 L 从 42 抬到 ~70 上下，**紫色岩相会丢失**；若要「既亮又保持蓝紫岩相」，只能走改法 A。

### ③ 基线读数需要用同一份 test 重跑基线树，才能填上「before/after 对照」

`island-readings-before.json` 目前是旧版 test 产出的（字段名不同），D8 的 before/after 对照与报告里的 before 数字需要用当前 test 重跑一次基线树：

```bash
T_ISLAND_TREE=/vol1/ai/projects/wyszz-new/frontend-rebuild-hm033 T_ISLAND_PREFIX=before- node test/t-island.mjs
# 或一键：node tools/test-island-e2e.mjs --all
```
（基线树 **只读 dist、不构建**，避免污染别人的工作副本。）

### ④ 非缺陷说明（供 Lead 归档）

- 接缝在 default 视角看不到紫色岩桥，是**岩桥挂在竖直壁面**、被两块顶面遮挡所致，符合 S1/S2 契约，不是穿帮；岩桥存在性的判据已改为像素差 + 无黑洞 + 无天窗 + 岩/草沿像素增加。
- 低视角（16°）能看到 12 个水晶像素属正常：水晶本来就挂在底面下沿，16° 已经能看到岛底下方；default(34°)/top(88°) 均为 0 ⇒ 水晶不再从侧面/上方穿出。

---

## 9. 复跑与结论

- 基线树 `frontend-rebuild-hm033` 的 `dist/web-internal` **存在**（version 0.3.3），因此 before 证据**已产出**，不是「基线 dist 缺失」的情况；基线树全程只读、未构建。
- after 证据基于 Lead 的最终几何重建后的 `dist/web-internal`；Lead 在 14:50 又重建过一次（`main-df3291edcd.js`），**建议按上面第 8 节 ③ 的命令重跑一次 `node tools/test-island-e2e.mjs --all`**，让 before/after 两份读数都用同一份 test 产出并刷新 evidence。
- 本报告第 4–7 节的数字取自最近一次完整运行（after 22/23 通过、pageerror 0；剩余 FAIL 均为断言口径问题，已按 Lead 的口径改完，见 `test/t-island.mjs` 的 ISL-C9 / D2 / D3 / D8）。
