# 开包动画实现技术栈

## 1. 总体形态

当前原型是一个不依赖后端的静态 Web 应用。Vite 负责开发和生产构建，Three.js 负责实时 3D/WebGL 渲染，GSAP 负责阶段时间轴。生产产物位于 `dist/`，可直接部署到 Cloudflare Pages。

原版产品采用 React Native WebView 作为宿主，原生 App 注入卡包、卡面、稀有度颜色与开关参数，Web 引擎负责动画、粒子、声音和手势。本原型先实现独立浏览器版本，保留后续接入 `window.PackOpeningBridge` 与 `ReactNativeWebView.postMessage` 的边界。

## 2. 核心依赖

| 层级 | 技术 | 版本/用途 |
| --- | --- | --- |
| 构建 | Vite | 8.1.4；开发服务器、资源处理和生产构建 |
| 包管理 | pnpm | 使用锁文件保证依赖可复现 |
| 3D 渲染 | Three.js | 0.185.1；场景、相机、网格、纹理、粒子和后处理 |
| 动画 | GSAP | 3.15.0；聚焦、撕封、退场、揭卡和加速时间轴 |
| 自动化 | Playwright | 1.55.0；桌面和手机全流程回归与截图 |
| 页面 | 原生 HTML/CSS | 状态提示、主题切换、设置、报告和下载入口 |

## 3. 渲染架构

### 场景与相机

- `THREE.Scene` 使用黑色背景和线性雾隐藏圆环远端。
- `PerspectiveCamera` 使用 60 度视场角，聚焦阶段通过 GSAP 推进和抬升。
- 15 个卡包复用几何和材质，按圆周均匀排布。

### 卡包材质

- 主体使用业务卡包图作为颜色纹理。
- 原版的卡包标题和 Logo 已烘焙在主体图，不由运行时排版。
- 顶部和底部封口在原版中是独立分段平面，通过颜色、压纹 shader 和顶点折叠生成。
- 深度遮罩主要调节左右边缘亮度，模拟软包装的鼓起和收边，并不生成真实厚度。

### 粒子系统

- 环境尘埃、撕封火花、旋涡、雪点、最终尘埃和烟花使用 `BufferGeometry`。
- 点粒子使用带硬核心和软衰减的 CanvasTexture。
- 撕封喷流由 `Points` 与 `LineSegments` 组合。
- 粒子位置、速度、重力、寿命和透明度在渲染循环中更新。

### 选择性 Bloom

- 使用两个 `EffectComposer`。
- Bloom Composer 只渲染粒子、封口光、撕封喷流和卡牌边框追光层。
- Final Composer 渲染清晰基础画面并叠加 Bloom 纹理。
- 这样可以复用原版 `strength 2 / radius 0.5 / threshold 0.1` 的观感，同时避免卡包和结果卡整面过曝。

### 自定义 Shader

- 卡包金属高光：根据 UV、时间和主题色计算移动反射。
- 卡背追光：黑白几何纹理阈值化着色，并叠加斜向移动光带。
- 卡面溶解：噪声阈值控制卡背到真实卡图的渐进切换。
- 边框追光：计算矩形周长位置，让绿金光带沿边缘运行并在结尾整圈收束。

## 4. 状态机与时间轴

主状态依次为：

```text
booting -> carousel -> focusing -> tear -> opening -> revealing -> complete
```

- Pointer Events 处理鼠标和触摸输入。
- `Raycaster` 判断点击命中的卡包。
- GSAP Timeline 管理阶段动画，避免用多个互相竞争的定时器。
- 揭卡阶段点击会把时间轴和溶解动画统一切换到 4 倍速。
- 重置时集中清理时间轴、粒子、音频实例和临时网格。

## 5. 音频与触觉

- Web Audio API 在启动阶段获取并解码音频为 `AudioBuffer`。
- 循环音乐、撕包纸声、whoosh、揭卡音和烟花音按状态与时间点触发。
- 音频加载失败时使用 Oscillator 合成提示音降级。
- 浏览器使用 Vibration API；接入 React Native 后应改为原生 light、medium、heavy 触觉桥接。

## 6. 资源与目录

```text
src/main.js              Three.js 场景、状态机、手势、时间轴和音频
src/styles.css           抽包页面 UI 与响应式样式
public/assets/packs/     四套用户自有卡包图
public/assets/audio/     音效和 cue manifest
scripts/build.cjs        Vite 构建与报告资源整理
scripts/verify.cjs       抽包全流程 Playwright 验证
scripts/verify-report.cjs 分析报告断图和响应式验证
```

## 7. 构建和部署

```powershell
pnpm install --frozen-lockfile
pnpm build
```

Cloudflare Pages 配置：

```text
Build command: pnpm build
Build output:  dist
```

生产构建包含抽包首页、HTML 分析报告、报告截图、UTF-8 文档响应头和源码下载 ZIP。`_headers` 明确为 Markdown 声明 `charset=utf-8`，避免浏览器按本地编码猜测。

## 8. 产品化接入边界

React Native 负责购买结果、鉴权、业务跳转、原生触觉和异常降级；Web 动画引擎只消费已经确定的展示数据。卡片结果必须由后端决定，前端动画不得参与随机结果计算。

推荐 Bridge 输入包括：

- `packImageURL`
- `cards[].cardFrontImageURL`
- `particleColor`
- `tearStripColor`
- `otherRaritySampleColors`
- `isRare`
- `soundEnabled`
- `hapticsEnabled`

推荐回传事件包括：`engineReady`、`haptic`、`telemetry`、`done` 和 `error`。