# 订阅里程碑弹窗 · 开发移交说明

> 一份给接手同学看的实现说明：整体结构、每个效果的实现方式、以及当前项目里调过的模型与动画参数。
> 线上预览：<https://subscription-milestone-popup.pages.dev>
> 本地调试：`python3 -m http.server 5178`（`.claude/launch.json` 里已配好 5178–5181 四个端口）

---

## 1. 项目构成

全部逻辑写在一个 `index.html` 里（约 1400 行），资源是外部的图片和模型。

```
index.html            页面结构 + 全部 CSS + 全部 JS（ES Module）
img/
  bg.png              背景图（App 发现页截图）
  StatusBar.png       顶部状态栏（9:41 / 信号 / 电量）
  close_btn.png       右上角关闭（本项目里绑的是「重播」）
  c2.png              描述文案切图
  laurel.svg          麦穗（第三阶段用，左右各一份，右边镜像）
  btn_{1,2,3}_{1,2}.png  三个阶段 × 两个按钮
  trophyconv_1k.glb   奖杯模型（实际加载的就是这个）
  planet-mask.png     星球圆盘的遮罩，驱动炫彩范围
  confetti.svg        彩屑形状（4 个星形 + 5 个矩形）
  UV/                 贴图 UV 排版说明与参考图（纯文档，页面不引用）
  trophyconv.glb      2K 贴图高模，未使用
  trophyconv_acrylic.glb  另一版材质，未使用
  icon.png            未使用
build.mjs             线上版构建脚本（见第 9 节）
handover.md           本文件
```

**运行时外部依赖**（CDN，通过 importmap 加载）：

| 包 | 版本 | 用途 |
|---|---|---|
| `three` | 0.170.0 | 3D 渲染 |
| `three/addons/` | 0.170.0 | GLTFLoader / SVGLoader / RoomEnvironment |
| `lil-gui` | 0.20.0 | 参数面板（**仅本地版**，线上版已剥离） |

---

## 2. 整体分层

画板固定 **375 × 812**，整块按视口等比缩放（`fit()`）：

```js
fitScale = Math.min(innerHeight / 812, innerWidth / 375, 1.4)
```

1.4 是桌面端的放大上限，避免大屏上糊成一片。`renderer.setPixelRatio` 跟着 `devicePixelRatio × fitScale` 走，封顶 3。

DOM 图层从下到上（`#phone` 内）：

| z-index | 元素 | 说明 |
|---|---|---|
| — | `.bg` | 背景图，`object-fit: cover` |
| 0 | `.veil` | 白色渐变 + 背景模糊蒙层 |
| 1 | `.glow` | 光环（DOM + SVG，不是 canvas） |
| **5** | `#stage` | Three.js canvas，**置顶** |
| 3 | `.copy` | 标题 / 描述 / 两个按钮 |
| 4 | `.status` `.close` | 状态栏、关闭按钮 |

canvas 之所以要压在文案之上（z-index 5）：光环是 DOM 的，波纹涨大时如果 canvas 在下，波纹会盖到玻璃模型上。canvas 本身背景透明且 `pointer-events: none`，所以下面的文案和按钮照常显示、照常可点。

### 坐标系

正交相机，视锥高度沿用原来 31° 透视相机在 z=0 处的可见高度：

```js
WORLD_H = 2 × 10 × tan(31°/2) ≈ 5.5465
WORLD_W = WORLD_H × 375 / 812 ≈ 2.5615
PX = WORLD_H / 812 ≈ 0.006831     // 1 世界单位 ≈ 146.4 设计 px
pyToWorld = py => (406 - py) * PX // 设计稿 py → 世界坐标 y（406 是画面竖向中心）
```

所以调参数时看到的 `324` 这类数字**都是设计稿 px**，写代码换算一律走 `pyToWorld()`，不要手算。

---

## 3. 光环

### 3.1 素材

光环不是图片，是运行时生成的 SVG（`glowSVG()`），三种形状：

| 层 | SVG 尺寸 | 形状 | 高斯模糊 |
|---|---|---|---|
| `inner` | 625 × 625 | 实心圆 r=162.5，`fill-opacity .2` | stdDeviation 75 |
| `middle` | 803 × 803 | 圆环 r=307，stroke-width 49 | 35 |
| `outer` | 1137 × 1137 | 圆环 r=474，stroke-width 49 | 35 |

颜色全部为 `rgba(color, .2)`，跟着状态切换（二阶段 `#2559F6`，三阶段 `#F2C877`，一阶段没有光环）。

### 3.2 入场：五层错峰成长

`GLOW_LAYERS` 五条轨道，共用 `GLOW_IN = 3.2s` 的时间线，用关键帧 `kf()` 求值：

```js
inner      times [0, .1291, .6965, 1]  scale [0,0,1,1]  ease ['linear','glow','linear']
middle     times [0, .0592, .5806, 1]  scale [0,0,1,1]  ease ['linear','glow','linear']
outer      times [0, .5214, 1]         scale [0,1,1]     ease ['glow','linear']
outer×1.4  times [0, .47,  1]          scale [0,1,1]
outer×1.85 times [0, .42,  1]          scale [0,1,1]
```

`glow` 缓动是 `cubic-bezier(.451, .009, 0, .98)`（从 sticker-peel 项目沿用），特征是**起步慢、尾段突然收住**。不透明度统一走：

```js
a = kf(p, [0, .2607, 1], [0, 1, 1], ['easeOut', 'linear'])
```

### 3.3 三阶段的持续波纹

只有第三阶段（`STATES[3].ripple = true`）才有「一圈圈往外扩散」。实现上**只让 `middle` 这一层担任波纹**（`RIPPLE_LAYER = 1`），其余四层入场结束就停在原位（`s = 1, a = 1`）—— 否则五层同时外推会糊成一团。

关键是把入场和循环接成**一条连续的时间线**，中间不能有停顿或跳变：

```js
RIPPLE_MAX   = 1.6      // 波纹最大 scale
RIPPLE_START = GLOW_IN × .5806 ≈ 1.8579s   // middle 在入场里「长满」的时刻

// t ≥ RIPPLE_START 之后：
u = (t - RIPPLE_START) / glowLoopDur + 1/RIPPLE_MAX
q = u - floor(u)                    // 相位 0..1
s = RIPPLE_MAX * q                  // 匀速外扩
a = kf(q, [0, .1, .62, 1], [0, 1, 1, 0], ['easeOut', 'linear', 'easeIn'])
```

`p0 = 1/RIPPLE_MAX = 0.625` 这个相位前置是核心：t 正好等于 `RIPPLE_START` 时 `q = 0.625`，`s = 1.6 × 0.625 = 1`，恰好接上入场结束的 scale 1 / 不透明度 1。所以从 1.86s 起波纹就无缝开始，不用等整套光环（3.2s）入场完 —— 中间那一秒多的空档就没有了。

每圈时长 `glowLoopDur = 4s`，在面板里可调（`max(.8, ...)` 兜底防止除零）。

### 3.4 透射背景板要同步

真透射模式下，玻璃里折射出来的背景是**另画的一份 canvas**（见 5.4），所以每次 `updateGlow()` 都会把每层的 `s` 和 `a` 存到 `o.s` / `o.a` 上，供 `updateBackdrop()` 复用。改光环逻辑时这两处必须一起改，否则玻璃里的光环和 DOM 上的对不上。

背景板里的光环不是贴 SVG，而是用 **erf 解析式直接算高斯模糊后的圆/圆环**（`buildGlowLayers()`），因为 Safari 下把 SVG 画进 canvas 可能污染画布、导致 WebGL 读不到贴图。形状参数在 `GLOW_SHAPES`，分辨率 192 × 192，够用且便宜。

---

## 4. 文案入场 & 按钮

四条文案走同一条 2 秒基准时间线（沿用 sticker-peel 的 `wr()`）：

```js
p = (t - textDelay) / 2      // textDelay = -0.15（整体提前 0.15s）
y = kf(p, [0, a, b, 1], [200, 200, 0, 0], ['linear', 'spring', 'linear'])   // 从下方 200px 弹上来
o = kf(p, [0, a, b, 1], [0, 0, 1, 1], ['linear', 'easeOut', 'linear'])
```

`spring` 是带过冲的回弹曲线：

```js
1 - exp(-x × 7.6657) × (cos(x × 6.7605) + 1.1339 × sin(x × 6.7605))
```

各元素的起止比例与换算成绝对秒数（`t = a × 2 - 0.15`）：

| 元素 | a | b | 开始 | 结束 |
|---|---|---|---|---|
| 标题 | .2601 | .7071 | 0.370s | 1.264s |
| 描述 | .2814 | .7285 | 0.413s | 1.307s |
| 按钮 1 | .4026 | .8496 | 0.655s | 1.549s |
| 按钮 2 | .4526 | .8996 | 0.755s | 1.649s |

绝对位置（`.copy` 内，单位 px）：

```
.title   top 524    26px / 500 字重 / 居中
.desc    top 568    width 253，上下 gap 4
.btn1    top 644    335 × 52
.btn2    top 710    335 × 52
```

### 标题的金色 + 扫光（仅第三阶段）

文字用 `background-clip: text` 做两层背景：上层是**光带**（213 × 58 的 `-77.23°` 白→透明渐变），下层是纯金色 `#EFBD5F`。光带做位移动画：

```css
background-position: -221px -11px → 195px -11px   /* 2.5s linear infinite，位移 416px */
```

麦穗 `laurel.svg` 14 × 32，`opacity: .5`，右侧那颗用 `scaleX(-1)` 镜像。

### 彩屑

- 触发时刻 `confettiAt = 0.4s`，数量 32，尺寸 `0.8 ×`，随机幅度 `0.65`
- 形状来自 `confetti.svg`（4 个星形带 `#25B4E1` / `#B0E7C2` / `#F2C877`，5 个矩形带 `#25B4E1` / `#F2C877` / `#DA4994`，原始 `fill-opacity` 在 .26–.55 之间）
- 渲染时把透明度**压到不低于 .55**（`Math.max(alpha, .55)`），否则爆开瞬间太淡看不清
- 物理是移植 sticker-peel 的：180Hz 定步长积分，`thrust 25–32` 的瞬时上冲在 0.04s 内衰减完，`burstDrag 2.6–3.2` 在 0.1s 内衰减，之后靠 `drag 0.3–0.7` 和重力 6.8 收尾；寿命 3.3–4.0s

---

## 5. 奖杯模型

加载的是 `img/trophyconv_1k.glb`（608 KB）。三个 GLB 的关系：

| 文件 | 大小 | 贴图 | 用途 |
|---|---|---|---|
| `trophyconv_1k.glb` | 0.58 MB | 3 张 1K PNG（147 / 185 / 120 KB） | **实际使用** |
| `trophyconv.glb` | 1.35 MB | 3 张 2K PNG | 高模备份 |
| `trophyconv_acrylic.glb` | 1.06 MB | 同 1K | 另一版材质 |

GLB 结构：1 mesh / 1 material / 3 nodes，材质带 `KHR_materials_transmission`（`transmissionFactor: 1`），`baseColorTexture` + `metallicRoughnessTexture` + `transmissionTexture` 三张图。

加载后**丢弃原材质、重建** `MeshPhysicalMaterial`（对齐 App 里 `ARContentView` 的绑定方式）：

```js
alphaTex.transmission = src.transmissionMap
alphaTex.roughness    = src.roughnessMap || src.metalnessMap || src.transmissionMap
map: src.map, metalness: 0, roughness: 1, transparent: true, side: FrontSide
```

`alphaSource` 默认取 `roughness`（即 GLB 的 metallicRoughness 图），面板里可切到 `transmission`。

模型会先居中、按最长边归一化，`modelMaxDim` 存下来给玻璃厚度用（`thickness = glassThickness × modelMaxDim`）。

### 5.1 入场动画

```js
entranceDur     = 1.4s
entranceTurns   = 1.5 圈
entranceRise    = 1.6 世界单位（起始下沉）
entranceEasePow = 3
```

```js
rise  = (1 - spring(p)) × -1.6
scl   = .35 + .65 × spring(clamp(p × 1.15, 0, 1))     // 从 35% 弹到 100%
extra = dir × 1.5 × 2π × (1 - (1-p)^3)                 // 额外旋转，ease-out
```

`entranceEasePow = 3` 是有讲究的：`1-(1-p)^n` 在 `p=1` 处速度和加速度都为 0，所以入场结束那一刻的角速度**正好等于持续自转速度**，不会先停住再起转。自转方向 `dir` 跟随 `spinSpeed` 符号，避免中途反向。

落定姿态：`yaw = -155°`，`pitch = 17°`，`roll = 0°`。

### 5.2 持续运动

```js
autoSpin   = true
spinSpeed  = 30 °/s
floatAmp   = 0.01（上下浮动，sin((t-D) × 1.6)）
```

浮动在入场结束后 0.6s 内淡入（`Math.min(1, (t-D)/.6)`），避免和落定瞬间打架。

模型整体不透明度在 **0.25s** 内从 0 淡入（`mats.forEach(m => m.opacity = fade)`）。

### 5.3 触控旋转

左右拖动转 Y 轴，带惯性；X/Z 轴只做跟手倾斜，松手回弹。

```js
dragSens = 0.6 °/px       inertia = 3.5
tiltMax = 8°              tiltSpring = 90      tiltDamping = 0.55
resumeDelay = 0.5s        resumeDur = 1.6s
```

几个细节：
- 拖动时 `spinMul = 0`（自转暂停），松手后先等 `resumeDelay`，再在 `resumeDur` 内用 `easeInOut` 加速回原速
- 角速度限幅 ±18 rad/s，并做 0.5 的平滑，防止最后一帧抖动导致「甩飞」
- 停顿超过 80ms 再松手，惯性清零
- 入场动画期间（`clock < entranceDur`）不接管触摸

### 5.4 玻璃材质（真透射）

这是整个项目最绕的一块。`matMode` 三档，默认 **真透射毛玻璃**。

**核心问题**：Three.js 的 `transmission` 只能折射 3D 场景里的不透明物体，**看不到后面的 DOM**。而我们的背景、蒙层、光环全是 DOM。

**解法**：在模型后面放一块铺满屏幕的平面（`backdrop`，z = -3），每帧用 2D canvas 按同样参数把 DOM 背后的内容重画一遍，再作为贴图喂给它：

```js
BD_SCALE = 0.5   // 半分辨率，背景本来就是糊的，够用
backdrop.onBeforeRender = r => {
  backdrop.material.colorWrite = r.getRenderTarget() !== null;   // 只在透射那一遍写颜色
}
```

`onBeforeRender` 里判断 render target 是关键：主画面渲染到 canvas（target = null）时不写颜色，平面隐形、DOM 正常显示；透射那一遍渲染到内部 RT 时写颜色，玻璃里折射出来的就是同一套背景。

**着色器补丁**（`realPatch()`，`onBeforeCompile` 注入）：

1. 把 `transmission_fragment` 里的 `material.transmission = transmission` 改成
   `transmission × (1 - texture2D(uMask, vMapUv).g × uSolid)`
   —— alpha 贴图为白的地方（数字、星环等细节）不透射，实体显示；为黑的地方是磨砂玻璃。
2. 把采样背景的 mip 等级从 `material.roughness` 换成独立的 `uBlur`。
   **这一条很重要**：原来两者绑在一起，表面一糙背景就被采样到最糊的 mipmap，直接糊成一块白，看着像实心。
3. 边缘亮边：`rim = pow(1 - N·V, 5)`，按 `uEdge × 0.8` 往白色提亮，模拟玻璃边框高光。
4. 前表面留一点通透（`1 - uSee`），配合下面说的背面层，让立方体内部的棱隐约透出来。

**参数**（默认值）：

| 参数 | 值 | 含义 |
|---|---|---|
| `glassRoughness` | 0.35 | 表面磨砂，只影响高光扩散 |
| `glassBlur` | 0.42 | 透射模糊，唯一决定透过去有多糊 |
| `glassThickness` | 0.2 | 厚度（× 模型最长边） |
| `glassIor` | 1.5 | 折射率 |
| `glassDispersion` | 0 | 色散，0 = 关 |
| `glassTint` | 0.12 | 体积色调浓度 |
| `glassEdge` | 0.55 | 边缘亮边 |
| `glassSolid` | 0.5 | 图案不透明度 |
| `glassSee` | 0.22 | 前表面通透程度 |
| `glassPatSolid` | 1.0 | 图案不受透明度影响 |
| `glassBack` | 0 | 背面层亮度（旧做法，默认关） |
| `frostTint` | `#f4f6ff` | 玻璃底色 |

**背面层**：同一份几何、`side: BackSide`、`renderOrder: 0`（前表面是 1）。它先画，前表面再留出 `glassSee` 那点通透，内部的棱就能透出来。

**另外两档**：`模拟毛玻璃`（alpha 贴图在「毛玻璃底」和「完全不透明」之间插值 + 菲涅尔加厚）、`App 原绑定（纯透明）`（完全按 App 的粗糙度/透明度绑定，不做任何加工）。

### 5.5 星球炫彩

圆盘区域随视角出现彩虹反光，三档材质都能叠加，不影响其它部分。

```js
planetIri = true      strength 0.23     angle 0      band 1
azimuth 131°          elevation 35°     shift 0.62   spread 0.42
```

色相跟**反射方向**走：`sweep = dot(reflect(-V, N), uIriDir)`，模型一转整片彩虹就扫过去；再叠一层 UV 竖向渐变，让同一时刻也能看到色带而不是一片纯色。

因为星球是纯白面，用加法会直接饱和成白，所以用**乘法着色**：把色带往白色里拉平（`mix(c, vec3(1), 0.28)`）再相乘，既保留球体光影，又能看到彩虹。

范围由 `img/planet-mask.png` 控制（从 alpha 贴图里离线识别出圆盘生成的，带羽化边），所以贴图重新排版也不会失效。

---

## 6. 背景蒙层

```css
left: -10px; top: -45px; width: 394px; height: 903px;     /* 比画板大一圈，盖住边缘 */
background: linear-gradient(to bottom, rgba(255,255,255,0) 0%, #fff 49.219%, #fff 100%);
backdrop-filter: blur(3.5px);
opacity: 0 → 1 在 0.3s 内
```

`veilBlur = 3.5` 是**按缩放折算后的实机值**（Figma 标注是 17）。滑杆直接写 CSS 变量 `--veil-blur`，不依赖渲染循环 —— 后台标签页里 rAF 会被挂起，走循环的话调了没反应。

背景板里那份是预先离线做好的（`bdVeil`），用 `ctx.filter = blur(17 × 0.5 px)` 一次性烘焙，不每帧算。

---

## 7. 三个阶段

基础动画完全统一，只有五处不同：

| | 一阶段 | 二阶段（默认） | 三阶段 |
|---|---|---|---|
| 按钮切图 | `btn_1_1` / `btn_1_2` | `btn_2_1` / `btn_2_2` | `btn_3_1` / `btn_3_2` |
| 光环 | 无 | `#2559F6` | `#F2C877` |
| 持续波纹 | 无 | 无 | 有（见 3.3） |
| 彩屑 | 无 | 有 | 有 |
| 麦穗 + 金色扫光 | 无 | 无 | 有 |

切状态会 `restart()` 从头播一遍，方便对比。

---

## 8. 交互

| 操作 | 行为 |
|---|---|
| 点击右上角 × | 重播 |
| 键盘 `R` | 重播 |
| 左右拖动画面 | 旋转奖杯（带惯性） |
| 右下角状态条 | 切换一二三阶段（线上版） |
| 右下角「开发移交 MD」 | 下载本文件 |

`restart()` 会重置触摸状态、时钟、彩屑物理，模型不动（不重新加载）。

---

## 9. 构建与部署

本地开发直接用 `index.html`，带完整 lil-gui 参数面板。

线上版走 `build.mjs`，**源文件一个字不改**，只在 `dist/` 里产出一份：

```bash
node build.mjs    # 生成 dist/
```

构建做了四件事：

1. **剥离参数面板** —— 删掉 `import GUI from 'lil-gui'` 和 importmap 里的对应条目，用一个空壳 Proxy 顶替 `GUI` 实例。这样所有 `gui.add(...)`、`f.addFolder(...)`、`updateDisplay()`、`gui.reset()` 都照常执行、只是不产生界面，**挂在 `onChange` 上的重绘逻辑（`paintGlow` / `applyMaterial` / `applyLights`）行为与本地完全一致**，不需要改业务代码。
2. **收起面板联动** —— `placeStateBar()` 清空，`ResizeObserver` 移除。
3. **右下角操作区** —— 把 `.hint`、下载按钮、状态条收进一个 `#corner` 竖排容器（提示 → 下载 → 状态），右对齐；同时把本文件一起拷进 `dist/` 供按钮下载。
4. **资源精简** —— 只拷贝 `index.html` 里实际出现的资源（14 个文件，1.2 MB），跳过 `img/UV/`、两个未使用的 GLB 和 `icon.png`。

部署：

```bash
npx wrangler pages deploy dist --project-name=subscription-milestone-popup --branch=main
```

> 注意：新版 wrangler 的 `pages project create` 会转发到 Workers 并失败，首次建项目必须加 `--force`。项目一旦建好，后续 `deploy` 不用带。

---

## 10. 已知问题 / 坑

**参数遗留**

- `P.glassDepth`（厚度渐变）**只声明了、没有实现**，改它没有任何效果。要么补实现（在 `realPatch` 里按 `vMapUv` 或法线做厚度插值），要么删掉。

**未使用资源**

- `img/trophyconv.glb`（2K 高模）、`img/trophyconv_acrylic.glb`、`img/icon.png` 页面都不引用。想减体积可以直接删，或者改成按需加载做「高清档」。

**兼容性**

- `ctx.filter` 在很老的 Safari 上不支持，会退化成不模糊。影响很小（奖杯位置基本是白的），所以没做兜底。
- `backdrop-filter` 同理，不支持时蒙层只是没有模糊，渐变仍在。

**CDN 依赖**

- Three.js 从 jsdelivr 拉。如果目标网络访问不稳定，需要把 `three.module.js` 和 `examples/jsm/` 下到本地 `vendor/` 并改 importmap。目前只有这一个外部依赖（lil-gui 已剥离）。

**改光环逻辑时**

- `updateGlow()` 里存的 `o.s` / `o.a` 和 `updateBackdrop()` 是耦合的，改一处必须改另一处，否则玻璃里的光环会和 DOM 上的错位。

**改材质时**

- 三个 patch（`realPatch` / `frostPatch` / `iriPatch`）都靠 `replace` 注入着色器字符串。Three.js 升级后如果 `ShaderChunk` 的片段名或内容变了，`replace` 会**静默失败**（不报错，只是补丁没生效）。升级 Three.js 后务必肉眼确认材质表现。
- `customProgramCacheKey` 里拼了 `P.planetIri`，切换炫彩开关时才会重新编译着色器。

---

## 11. 参数速查（`const P`）

一共 86 项，全部有中文注释。按面板分组：

```
顶层         state speed
卡面换图      coverOn coverFit coverMask coverSolid coverUseFill coverFill
光照         ambientOn/Color/Intensity
             keyOn/Color/Intensity/Azimuth/Elevation
             fillOn/Color/Intensity/Azimuth/Elevation
             envIntensity envRotation showLights
光环         glowColor glowY glowScale glowLoop glowLoopDur
奖杯模型      modelY modelSize entranceDur entranceTurns entranceRise entranceEasePow
             floatAmp alphaSource matMode frostTint
             glassRoughness glassBlur glassEdge glassSolid glassBack glassSee
             glassPatSolid glassTint glassThickness glassIor glassDispersion
             frostOpacity frostRoughness frostEdge
星球炫彩      planetIri planetIriStrength planetIriAngle planetIriBand
             planetIriAzimuth planetIriElevation planetIriShift planetIriSpread
模型旋转      yaw pitch roll holdPose spinSpeed frontFlip
触控旋转      dragSens inertia tiltMax tiltSpring tiltDamping resumeDelay resumeDur
彩屑/文案     confettiAt confettiCount confettiSize confettiSizeVar textDelay
             veilBlur veilIn
```

面板顶部的「📋 复制参数」会把当前所有值导出成可直接粘回代码的 `key: value,` 文本，调完参很实用。

### 非面板常量

这些在代码里是 `const`，改需要动源码：

```js
GLOW_IN = 3.2          // 光环整体入场时长
RIPPLE_LAYER = 1       // 波纹由哪一层担任（索引 GLOW_LAYERS）
RIPPLE_MAX = 1.6       // 波纹最大 scale
COVER_PX = { x0: 9.5, y0: 424, x1: 406, y1: 820.5 }   // 卡面换图的贴图矩形（1024 基准）
BD_SCALE = 0.5         // 透射背景板分辨率
BD_Z = -3              // 背景板 z
WORLD_H ≈ 5.5465       // 正交相机视锥高度
```

---

## 12. 卡面换图（备用功能）

`P.coverOn = false` 默认关闭。打开后可以换掉奖杯上那张「节目卡面」，实现方式对齐 App 的 `ARTextureGenerator`：以原始 color 贴图为底，把新图合成到固定矩形，再用它替换材质的 `map`。

```
内容区域：x = 9.5, y = 424, w = 396.5, h = 396.5（1024 基准，左上角原点）
         对应 App 的 2048 下 x=19, y=848, w=793, h=793
```

用 **canvas 像素**而不是 UV 数值，是为了绕开「UV 的 V 从下往上、canvas 的 Y 从上往下」这个特别容易搞反的地方。遮罩图要同步重算，否则卡面会沿用老图案的透明度 —— `applyCover()` 里两件事是一起做的。

详见 `img/UV/trophyconv-UV说明.md`。

---

## 13. 调试入口

控制台里挂了一些钩子（生产版也有，体积可以忽略）：

```js
__P              当前全部参数
__restart()      重播
__applyState(n)  切到第 n 阶段
__applyMaterial() __applyLights()  手动刷新材质 / 光照
__mats           材质数组          __THREE  Three 命名空间
__confetti       彩屑对象
__loadCover(url) __applyCover()   换卡面
__copyParams()   复制参数
```
