# 拼图运行时限时与道具系统设计 2026-04-29

## 背景

拼图运行时从纯粹的无压解谜升级为限时关卡，需要同时补齐三类体验：

1. 不同难度有明确倒计时，超时即失败。
2. 底部固定 3 个轻量道具：提示、查看原图、冻结时间。
3. 道具使用必须经过确认弹窗并消耗 `1` 光点，确认弹窗期间暂停关卡计时。

本设计只处理拼图运行时，不改拼图创作链、发布链和广场推荐链。

## 运行态字段

`PuzzleRuntimeLevelSnapshot` 增加以下字段：

1. `timeLimitMs`：当前关卡限时。
2. `remainingMs`：后端或本地运行态计算出的剩余时间。
3. `pausedAccumulatedMs`：已累计暂停时长。
4. `pauseStartedAtMs`：当前是否处于暂停中；有值表示暂停开始时间。
5. `freezeUntilMs`：冻结时间道具生效截止时间；冻结期间倒计时不减少。

`status` 增加 `failed`。当 `remainingMs <= 0` 且关卡尚未通关时，状态进入 `failed`，后续交换、拖动、排行榜提交都拒绝。

## 难度限时

拼图关卡切割规格和倒计时由统一关卡配置函数解析，不再按网格规模单独推导时间：

| 关卡     | 切割规格 | 限时       |
| -------- | -------- | ---------- |
| 第 1 关  | `3x3`    | `300000ms` |
| 第 2 关  | `4x4`    | `300000ms` |
| 第 3 关  | `5x5`    | `300000ms` |
| 第 4 关  | `5x5`    | `210000ms` |
| 第 5 关  | `5x5`    | `210000ms` |
| 第 6 关  | `6x6`    | `240000ms` |
| 第 7 关  | `5x5`    | `210000ms` |
| 第 8 关  | `7x7`    | `270000ms` |
| 第 9 关  | `5x5`    | `240000ms` |
| 第 10 关 | `7x7`    | `270000ms` |

第 11 关开始，每 6 关循环复用第 5 关到第 10 关的配置，即 `5x5/210000ms`、`6x6/240000ms`、`5x5/210000ms`、`7x7/270000ms`、`5x5/240000ms`、`7x7/270000ms`。

同作品下一关必须使用同一个运行时关卡序号继续推进。跨作品相似推荐只切换到候选作品的第一张图，运行时关卡序号、切割规格和倒计时继续按当前 run 累进，不重置难度循环。

失败状态点击“重新开始”时，不进入作品第 `1` 关，而是重开当前失败关卡：前端需要传当前关 `levelId`，服务端按该 `levelId` 在作品内的位置恢复 `currentLevelIndex`、切割规格和倒计时。

后续若扩展更多难度，只能通过同一个关卡配置解析函数扩展，不允许在 UI 里写死另一套时间。

## 计时规则

有效消耗时间计算：

```text
effectiveElapsedMs = nowMs - startedAtMs - pausedAccumulatedMs - activeFreezeElapsedMs
remainingMs = max(0, timeLimitMs - effectiveElapsedMs)
```

其中：

1. 弹窗打开、设置面板打开、查看原图覆盖打开时，运行态需要暂停。
2. 冻结时间生效时，画面播放冻结特效，并展示冻结剩余时长。
3. 通关时 `elapsedMs` 使用有效消耗时间，不把确认弹窗、查看原图和冻结时间计入成绩。
4. 失败后保留棋盘，不弹通关结算。
5. 正式后端 run 的前端倒计时归零时，需要主动刷新一次 `getPuzzleRun`，让 SpacetimeDB 侧把 `failed` 状态写回快照，避免只停留在本地视觉失败。

## 道具规则

### 提示

提示道具只演示，不替玩家移动。

演示对象选择：

1. 优先选当前棋盘中拼块数量最多、且尚未完全处于正确位置的合并块。
2. 若没有合并块，选择一个不在正确格子的单块。
3. 演示从当前所在格移动到该块锚点的正确格，结束后回到原位。

### 查看原图

查看原图是开关按钮：

1. 打开后把原图以半透明方式覆盖在拼图棋盘上。
2. 覆盖期间暂停倒计时；确认弹窗关闭到覆盖层显示之间不得恢复计时，正式后端 run 也需要保持 `pauseStartedAtMs`。
3. 再次点击关闭覆盖并恢复计时。

### 冻结时间

冻结时间确认后：

1. 播放冻结视觉特效。
2. 显示冻结剩余时长。
3. 第一版冻结 `10000ms`。
4. 若玩家打开冻结确认弹窗前视觉上仍是 `playing`，但确认扣费期间正式 run 已被服务端计时结算为 `failed`，服务端不得返回“操作不合法”。本次调用视为一次边界同步，已预扣费用必须退款，只返回失败态快照并刷新存档；前端关闭道具确认窗，展示失败面板，不播放冻结特效。

## 计费规则

每次确认使用道具消耗 `1` 光点。

正式后端运行态复用现有资产操作钱包预扣链路，新增道具 `asset_kind`：

1. `puzzle_prop_hint`
2. `puzzle_prop_preview`
3. `puzzle_prop_freeze_time`

本地调试 run 没有真实用户钱包，不伪造扣费，只保留同样的确认交互与运行态效果。

若扣费或道具过程失败，确认弹窗保持打开并继续暂停倒计时，在弹窗内展示失败原因；只有成功确认后才关闭弹窗并播放对应反馈。

补充规则：冻结时间的边界同步不属于道具使用成功。服务端若发现 run 已超时失败，应退回本次预扣、把失败态落库并返回最新快照，避免玩家在确认窗内看到“操作不合法”。

## UI 规则

1. 底部只放 3 个道具按钮，不写规则说明文案。
2. 点击道具弹出独立确认窗口，不在底栏下方展开。
3. 确认窗口打开期间暂停计时。
4. 按钮使用图标和短标签；不可用时降低透明度。
5. 失败状态使用简洁弹窗展示，可返回或重新开始，不与通关结算混用。

## 画布表现修正

本轮同步修正合并块视觉：

1. 合并块之间不再使用额外 `p-1` 缝隙，拼图块需要贴合。
2. 单块和大块使用同一套边界描边宽度与颜色。
3. 外轮廓和凹入转角都需要圆角化。
4. 新合并产生时，在新大块中心播放一次简洁闪光，不显示文字提示。