# 抓大鹅运行态 3D 几何体实验 2026-05-02

## 1. 实验目标

本轮只验证抓大鹅运行态把可消除物从 2D 纯色几何图案切换为 3D 几何体后的可读性、点击手感和堆叠碰撞观感。

3D 表现层必须满足：

1. 圆形图案映射为球体。
2. 方形图案映射为方块。
3. 三角形、菱形、五角星、六边形、胶囊、心形、梯形、平行四边形等现有视觉键映射为近似 3D 几何体。
4. 物体在圆形空间内保持边界约束，并使用物理模拟产生轻微碰撞、堆叠、晃动效果。
5. 点击、备选栏、消除、胜负判定仍使用当前后端权威快照与前端即时反馈协议，不把规则真相迁到前端。

## 2. 回退要求

这是一次可取消实验，不替换现有 2D 方案。

1. 现有 `Match3DVisualIcon`、`Match3DToken` 和托盘 2D 图案渲染代码必须保留。
2. 新增 3D 表现层只作为运行态棋盘的可选渲染分支。
3. 当浏览器不支持 WebGL、3D 依赖加载失败或实验开关关闭时，运行态必须自动回到现有 2D 图案表现。
4. 托盘继续使用当前 2D 图标，便于玩家识别已选物品，也便于实验失败时快速回滚。

## 3. 工程落点

本轮只改前端表现层：

```text
src/components/match3d-runtime/Match3DPhysicsBoard.tsx
src/components/match3d-runtime/Match3DRuntimeShell.tsx
src/components/match3d-runtime/Match3DRuntimeShell.test.tsx
src/components/match3d-runtime/match3dRuntimePresentation.ts
src/components/match3d-runtime/match3dVisualAssets.tsx
```

新增依赖：

```text
three
cannon-es
@types/three
```

3D 棋盘默认启用；需要快速回到当前 2D demo 表现时，在运行态 URL 上追加任一参数：

```text
?match3dRender=2d
?match3d3d=off
```

3D 分支只读取后端快照中的物品坐标、层级、可点击状态和视觉键。物理碰撞、轻微堆叠和几何体姿态只作为前端表现层，不改变消除规则、备选栏规则、胜负判定或最终权威快照。

`match3dVisualAssets.tsx` 保留 2D 纯色几何图案映射，运行态托盘继续使用该 2D 图标；`match3dRuntimePresentation.ts` 收口显示层坐标和状态兼容，避免异常旧坐标把 2D 或 3D 物体推到圆形边界外。

## 4. 验收口径

1. `/match3d` 能打开并默认看到 3D 几何体棋盘。
2. 3D 几何体保持在圆形区域内，不被圆形边界裁切到不可点。
3. 物体进入场景后有轻微物理碰撞和堆叠稳定过程。
4. 点击 3D 物体后仍执行原有乐观入槽、后端确认、三消反馈和结算。
5. 单元测试仍覆盖 2D 回退图案，确保回退路径没有被删除。
6. 390px 移动端与桌面端均不能出现横向溢出，顶部状态、圆形棋盘和 7 格备选栏都要完整可见。

## 5. 锅型容器优化

2026-05-02 追加一轮 3D 表现优化，把运行态圆形空间明确解释为一口有固定深度和确定边界的锅。

编码口径：

1. 相机改为俯视角，玩家优先看到锅内物体的平面分布、遮挡关系和向上堆叠。
2. 3D 场景里的圆形区域拆成锅底、锅壁和锅沿三层视觉结构，锅壁有固定高度，锅沿明确标出边界。
3. 物理世界使用同一个锅内半径作为水平活动边界，所有可消除物体的初始位置和运行中位置都必须被约束在圆形锅内。
4. 物体受到重力后只允许在锅内碰撞、滑动、翻滚和向上堆叠，不能因为碰撞或初始坐标散落到圆形区域外。
5. 该优化仍只属于前端 3D 表现层，不改变后端运行态坐标、点击权威判定、备选栏、消除和胜负规则。