Genarrative/docs/technical/PUZZLE_RUNTIME_TIMER_AND_PROPS_2026-04-29.md

拼图运行时限时与道具系统设计 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 里写死另一套时间。

计时规则

有效消耗时间计算：

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. 新合并产生时，在新大块中心播放一次简洁闪光，不显示文字提示。