NumberSwipe_New/modes/01-number-stroke/docs/GDD.md

# 玩法一 · 数字一笔

本文只描述**玩法一**。玩法三（六边一笔）有自己的目录和 GDD，见仓库 [`docs/PRODUCT.md`](../../../docs/PRODUCT.md)。玩法三虽然也是顺序一笔画，几何和墙都独立，不要把墙或六边形补进本玩法。

用一次滑动，按数字规定的顺序，把盘面上每一块都走遍。规则、交互、关卡、竖直切面都以能直接实现为准。关卡、资源、文案全部原创。

---

## 1. 一句话

在不规则拼板上画一条哈密顿路径：格子可大可小，大格只算一步；盘上预先写好的数字，必须刚好在那一步走到。

## 2. 产品定位

| 项 | 决定 |
|---|---|
| 类型 | 单机、离线、无体力、无计时的逻辑 puzzle |
| 平台 | 手机竖屏。本玩法 V1 先在 `modes/01-number-stroke/web/` 可玩，再进 Cocos 本玩法场景 |
| 单局 | 15–90 秒想，3–8 秒画完 |
| 会话 | 通勤 3 关，睡前 15 关 |
| 对象 | 喜欢 Flow Free、Numberlink、一笔画、数回的人；不靠剧情、不靠养成 |
| 付费 | 竖直切面免费无广告。上线后再加去广告 + 提示视频 |

卖点不是“又一个一笔画”，而是：**数字把无限路径收成唯一解，大格子把几何邻接和步数拆开。**

没有数字时，一笔画路径往往很多。加上两三个序号，解立刻变成一条。难度结构就是这三条：数字少、解唯一、横长/纵长格让难度陡起来。

## 3. 核心循环

1. 看盘：哪些格写了数字，哪些是大格，洞在哪。
2. 推：从已知序号往两边挤，排除走不通的岔路。
3. 画：手指从当前格滑到邻格，沿途自动填序号。
4. 错了就沿原路退，或一键重开。不会死局锁死。
5. 全填满且数字全部对上 → 过关，下一题。

没有分数、连击、限时。爽感来自“这条路只能是这样”和滑过时格子亮起来。

---

## 4. 规则（权威）

### 4.1 盘面

- 盘面落在整数网格上。每个**格**是轴对齐矩形，占 `w×h` 个单位格，`w,h ≥ 1`。
- V1 允许的尺寸：`1×1`、`1×2`、`2×1`、`2×2`。V1.1 追加 `3×3` 大连块。
- **V1.1 起追加异形格**（俄罗斯方块式拼块）：2～4 个单位格四向连通，目录为 I/L/S/T/O（含旋转与镜像），JSON 里用 `shape` 偏移列表表达。规则与矩形完全一致：占多个单位格、仍只计 1 步、按单位边算邻接。
- 每个格无论面积，都是图上的**一个节点**，路径里只计 **1 步**。
- 单位格要么属于恰好一个格，要么是空洞（不可走、不显示底板）。
- 盘面可以不规则，可以有洞。

### 4.2 邻接

两个格相邻，当且仅当它们共享至少 1 个单位长度的边（异形格按它占的每个单位格逐对判断）。只认四向，不认角对角。

推论：`2×2` 可以同时和它四边贴着的多个 `1×1` 相邻。这是难度的主开关——步数是 1，出口却有 4～8 个。异形格的凹口让「贴着几个格」更不规则，是 V1.1 的难度来源之一。

### 4.3 路径

目标：在格图上找一条**哈密顿路径**。

- 每个格恰好经过一次。
- 只能走到相邻且尚未走过的格。
- 经过第 `k` 个格时，该格显示数字 `k`（从 1 起）。
- 路径是一条线，不是树，不能分叉，不能跳。

### 4.4 线索格

部分格预先写了正整数 `c`，带描边，开局就看得见。

- 路径走到这个格时，步号必须等于 `c`；反过来，第 `c` 步也必须走到这个格。
- 盘上可以没有 `1`：起点未给定，玩家自己判断从哪起手。这是中后期难度，不进前 12 关。
- 线索可以在路径中段，不必是起点或终点。
- 同一盘线索互不相同，且 `1 ≤ c ≤ N`（`N` 为格数）。
- 线索可以不包含 `N`（终点未给定）。

**V1.2 奇偶线索**：格子也可以写「奇」或「偶」，代替确定的数字。

- 「奇」要求该格的路径步号是 `1、3、5…`；「偶」要求 `2、4、6…`。按整格计步，和占用面积无关，支持 `3×3` 与异形拼块。
- 同一格只填一种线索：数字或奇偶；同一盘允许多个「奇」和「偶」，并可与数字线索混用。
- 未走时居中显示「奇／偶」和整格描边。走对后显示实际步号，在下方保留小字「奇／偶」；走错时红底显示实际步号，角标保留「奇／偶」要求。
- 起点规则不变：有数字 `1` 时只能从它起手；没有 `1` 时可从任意格尝试，从「偶」起手会产生冲突。
- 第三包「奇与偶」先提供 6 关体验（`pack-3-parity.json`）；每条奇偶线索都必须参与唯一性，不能只是普通方格盘上天然成立的奇偶条件。

### 4.5 对错

走的过程允许“暂时错”：

- 踩到线索格但当前步号不满足数字或奇偶要求：该格变冲突态（红底），数字显示当前步号，角标显示原线索，避免只靠颜色。
- 当第 `c` 步走到预定数字 `c` 所在格以外的任意格，也立即冲突。错误格红底显示当前步号并轻晃，不显示叉号；无需等到踩上预定格再判错。
- 原始预定数字与「补数字」新增的数字都适用；补数后即时检查现有路径。奇偶要求只约束本格，不占用其他同类步号。
- 错误格单独轻晃 280ms，连接线保持紫色。补数字造成已有路径冲突时也轻晃；退回 / 重开立即停止。减弱动态效果开启时仅标红。
- 冲突不打断手势，可以继续画，也可以退回。
- **过关条件（同时满足）**：所有格都走过，且全部数字线索和奇偶线索都满足。
- 未过关时没有失败弹窗。死路的反馈是：没格可走了，但还没填满或还在冲突。

### 4.6 内容铁律

每一关在发布前必须通过求解器验证：

1. 至少 1 条合法哈密顿路径满足全部线索。
2. 恰好 1 条。
3. 线索数量尽量少：在仍唯一的前提下，优先少线索、优先去掉 `1` 和 `N` 这类“端点暗示”。
4. 有奇偶线索时，逐条删除后都应出现多解；`validate` 会拒绝冗余奇偶线索。

前 8 关可以故意多给线索，用来教学，不追求最简线索。

---

## 5. 交互

### 5.1 手势

单指。

| 手势 | 行为 |
|---|---|
| 点在合法起点 | 该格变为路径第 1 步。若该格是线索且 `c ≠ 1`，进入冲突态，但仍算第 1 步 |
| 按住滑向相邻未走格 | 追加一步，画连接短边，格子填色并写步号 |
| 点按或滑到任意已走格 | 保留该格及之前的路径，一次撤掉后面的填色、短边、步号与冲突；不松手即可换方向继续画 |
| 滑到不相邻的未走格 | 忽略；前进仍只允许四向邻接 |
| 在空白处松手 | 路径保留，下次从末端继续，或点更早的已走格直接回退 |
| 点末端旁的未走格 | 追加一步，兼容点按操作 |

触屏命中死区为格四周 8%，鼠标为 14%。快速滑动插值补采样；实际触点落到历史格时优先回退，避免跳跃采样误追加途中的格。仅跟踪一个主指针。

合法起点：

- 若存在线索 `1`：只能从该格起手。点别的格无效果，线索 `1` 轻抖一次。
- 若不存在线索 `1`：任意非空洞格都可起手。

### 5.2 按钮

盘面下方三个按钮：

1. **重开**：清空路径，本局已补出的数字保留。
2. **补数字**：在当前待解区间补一个中间数字，让玩家继续推路线。规则见 §10。
3. **指路**：指出下一步或应退回的位置，保留原来的提示方案。

顶部：`{pack}-{index}`、剩余未走格 `□ × n`、返回选关。音效 / 振动在选关页设置；正式壳接管通用设置。

没有倒计时，没有步数惩罚。

### 5.3 输入状态机

```
Empty
  → 合法起点按下 → Drawing
Drawing
  → 滑到相邻未走格 → Drawing（N 增加）
  → 滑到任意已走格 → Drawing（截短路径，保留目标格）
  → 松手           → Idle（保留路径）
Idle
  → 从末端按下     → Drawing
  → 点更早的已走格 → Drawing（截短路径，可继续滑动）
  → 重开           → Empty
  → 全填满且无冲突 → Cleared
Cleared
  → 短庆祝后自动进下一关，或点下一关
```

任何时候点重开都回到 Empty。Cleared 后本关路径锁住，不能再改。

---

## 6. 反馈与手感

逻辑 puzzle 的板要干净，动效只服务三件事：我走到哪了、哪错了、过没过。

| 事件 | 反馈 |
|---|---|
| 追加一步 | 格 80ms 弹性放大回 1.0；相邻短边弹出；步号 fade-in；轻振动 |
| 撤销一步 | 格褪回未走色；短边收回；无振动 |
| 踩中线索且步号正确 | 描边闪白一次。这是“推对了”的主奖励 |
| 冲突 | 单格变红并轻晃，连接线保持紫色；短振动，不弹窗 |
| 死路未过关 | 当前格轻轻抖。不弹“失败” |
| 过关 | 全盘路径色提到更亮，短边顺次扫过 200–300ms，然后切下一关。不要大烟花、不要全屏撒纸片 |
| 非法起手 | 线索 `1` 抖动 |

视觉与动效的权威规格已迁到仓库 [`docs/design.md`](../../../docs/design.md)（令牌、字阶、组件、动效四档、过关时间线）。下面的配色与反馈表保留为规则口径，数值以设计规范为准。

配色 V1（浅色主题）：

- 未走：中灰
- 已走：单一主色（蓝紫）
- 线索描边：未走线索 / 奇偶格与线索数字同色（墨 `#23243A`）；起点和已走线索为灰白 `#DFE1EC`
- 起点数字 `1`：开局蓝紫底、白字、灰白描边；数字放大为单位格的 62%（原为 42%），描边收细至 4.5%；只是视觉提示，按下后才计入路径。重开和撤销至空盘时恢复此样式。
- 冲突：红
- 背景：白
- 数字：已走格用深色；未走线索格用白字

不要每关换主题色。识别数字和冲突优先于换皮。

音效：落子短音（音高随步号轻微上升，到 12 后循环）、冲突闷音、过关和弦。可关。

---

## 7. 关卡语言

难度不靠计时，靠这五个旋钮。一次只加一个。

| 旋钮 | 作用 | 何时引入 |
|---|---|---|
| 格数 `N` | 8–12 教学，12–16 常规，17–22 后期 | 全程 |
| 大格 | `2×2`/`3×3` 出口多、只计 1 步；`1×2`/`2×1` 让难度突然抬升 | 第 4 关起 `2×2`，第 9 关起长条，第二包起 `3×3` |
| 异形格 | L/I/S/T 拼块：邻接更不规则，凹口改变分叉结构（V1.1） | 第 11 关起（第二包） |
| 空洞 | 切断看似相邻的格，强迫绕路 | 第 6 关 |
| 线索位置 | 中段线索比起点线索更要推理 | 第 5 关 |
| **线索步号差** | **难度的主旋钮**：相邻线索差得越远越难。开局 5～7 步内给一个近距引导线索，玩家就有起手方向；难度靠后面拉开差距 | 全程（V1.1 起作为生成约束） |
| 无线索 `1` | 起点未知 | 第 13 关之后 |
| 奇偶线索 | 只约束步号奇偶，结合大块改变走法；需证明参与唯一性 | V1.2 第三包 |

不做的旋钮（V1）：斜走、传送、单向边、冰格、颜色门、限时。先把主规则做到手熟。

1-1 到 1-5 的坐标已经写在 `levels/pack-1-tutorial.json`。实现时直接读这个文件。

### 7.1 教学 12 关（必须手做，不生成）

| 关 | 教什么 | 盘面约束 |
|---|---|---|
| 1-1 | 滑动、自动出数字 | 3 个 `1×1` 一横，只标 `1` |
| 1-2 | 必须走完所有格 | L 形 4 格，标 `1` 和 `4` |
| 1-3 | 可以退回 | 小岔路，标 `1`。第一次死路用抖提示退 |
| 1-4 | 大格 = 1 步 | 一个 `2×2` + 三个 `1×1`，标 `1` |
| 1-5 | 中段线索 | 约 7 格，标 `1` 和 `4` |
| 1-6 | 空洞 | 明显的缺口，看起来近其实不相邻 |
| 1-7 | 先推再画 | ~10 格，两个中段线索。正解需要先排除一条岔路 |
| 1-8 | `2×2` 当枢纽 | 一个 `2×2` 连接三个方向 |
| 1-9 | 横长条 | 第一次 `1×2`，出口在长边上 |
| 1-10 | 竖长条 | `2×1` |
| 1-11 | 两个大格 | `2×2` + `1×2` |
| 1-12 | 综合小考 | ~12 格，3 个线索，唯一解，不过分绕 |

1-4 是关键：玩家必须理解“这块很大，但数字只加 1”。过不了这关，后面全废。

### 7.2 结构

- 一包 8 关。包号就是顶部的 `pack`。
- 包内由易到难，最后一关是本包小 Boss。
- V1 内容量：教学 12 关 + 4 包 × 8 = **44 关**。够验证循环，不够上架。上架目标另定 200+。
- 正常版本选关按通关进度线性解锁；独立 HTML 试玩版全部 26 关开放，可直接选择任意关卡，不需要通关前置关。
- 没有每日挑战、没有联机（V1）。

### 7.3 规则样例盘（只用于讲规则，不上架）

一块 15 格的原创样例，用来对齐邻接和大格，不进资源表。`tests/solver.test.ts` 用同一块盘做求解器回归。

单位网格 5×5，行从上到下 0–4，列从左到右 0–4：

```
A A a b c
A A . d e
f g h B B
. i j B B
1 l m . .
```

- `A` = `2×2` 于 (0,0)
- `B` = `2×2` 于 (3,2)，带线索 `6`
- `1` 是线索，位于 (0,4)
- 其余字母是 `1×1`
- `.` 是空洞
- `N = 15`

邻接检查：`A` 贴 `a`（右边）、`f`、`g`（底边），不贴 `h`（只碰角）。`B` 贴 `d`、`e`（顶边）、`h`、`j`（左边），底边全是空洞。`1` 只贴 `l`，度为 1，所以必是路径端点。

唯一解：`1 → l → m → j → h → B → d → e → c → b → a → A → f → g → i`。`B` 面积 4 格，只占第 6 步。

错误走法演示：`1 → l → m → j` 之后往左进 `i` 看起来顺手，但那样 `B` 最早也要到第 8 步，踩上去显示红 `8`：这是冲突态的标准演示。正确走法是 `j` 之后先进 `h` 当第 5 步，再进 `B` 当第 6 步。

---

## 8. 生成器与求解器

手做教学关。第 13 关起允许生成，但每关必须人过一眼：解是否“漂亮”（没有无意义绕圈、线索是否读得清）。

### 8.1 求解器

输入：格列表（矩形 / 异形 + 可选数字或奇偶线索）。输出：满足全部线索的哈密顿路径。

- `N ≤ 22`，回溯即可。先走度小的节点，线索格在步号到达前剪枝。
- 线索格 `c`：若当前步号已超过 `c` 而该格未走，剪枝；若走到时步号 ≠ `c`，剪枝。
- 奇偶格：每次尝试进入（包括起点）都按实际步号检查奇偶，不符则剪枝。`ignoreClues` 同时忽略数字与奇偶条件。
- 发布流水线：`paths.length === 1` 才写入关卡表。

### 8.2 生成流程

1. 随机或用模板铺格 + 空洞，保证格图连通。V1.1 起模板含异形拼块（I/L/S/T/O，随机旋转镜像），并保证每个多单位格都被作者解真正穿过（不当端点）。
2. 随机找一条哈密顿路径作为“作者解”。
3. 从路径上抽 2～4 个位置当线索（偏中段，少用 `1`/`N`）。V1.1 起带线索 `1` 的关先在 `1` 之后 4～7 步放一个**引导线索**（开局近距指引），再用其余线索拉开步号差上难度。
4. 跑求解器。若解 > 1，加线索或换位置；若解 = 0，丢弃。
5. 尝试删线索，能删到仍唯一就删。
6. 导出 JSON。

### 8.3 关卡文件

```json
{
  "id": "2-3",
  "pack": 2,
  "index": 3,
  "cellSize": 64,
  "cells": [
    { "id": "a", "x": 0, "y": 0, "w": 1, "h": 1, "clue": 1 },
    { "id": "b", "x": 1, "y": 0, "w": 2, "h": 2 }
  ]
}
```

- `x,y` 是单位格坐标，原点左上。
- V1.2 可写 `"parity": "odd"` 或 `"parity": "even"`，与 `clue` 互斥；省略表示没有奇偶要求。例：`{ "id": "big", "x": 1, "y": 1, "w": 3, "h": 3, "parity": "odd" }`。
- 不存解。解由求解器在编辑器里验证，运行时只做规则模拟。
- 提示用的“下一步”在编辑器烘焙进可选字段 `hintPath`，避免端上枚举。若缺失，运行时现算（N 小，可接受）。

---

## 9. 界面与流程

```
（壳：选玩法）→ 本玩法选关（默认停在第一关未通） → 对局 → 过关 → 下一关
                                         ↘ 菜单：本玩法关卡列表 / 返回壳
```

设置、广告、返回首页属于壳，见 `shared/`。本玩法对局页不实现去广告购买。

对局层从上到下：

1. 安全区
2. 顶栏：关号、剩余格、汉堡菜单
3. 盘面（水平垂直居中，按短边缩放，四周留指宽）
4. 手势说明「按住滑动连线 · 点已走格回退」；底栏：重开、补数字、指路
5. 底 banner 广告位：竖直切面放占位，正式包未去广告时才显示

过关不进独立结算页。短动画后自动下一关。最后一关回选关。

文案尽量少。规则用 1-1～1-4 教完，不写长教程。1-1 顶部一行：“从一个数字滑到邻格”。1-4 一行：“大格也只算一步”。之后无文案。

---

## 10. 提示、存档、设置

**补数字**

- 从唯一解中取当前尚未解开的数字区间，选择靠近中点的一个步号。例如已有 `1` 与 `9`，补出 `5`；再请求可继续缩小区间。
- 正确前缀已走过的区域不再补数；走错时仍按真实解补数，不沿错误路线给数字。
- 每次只增加一个固定数字，不自动追加路径。该数字参与冲突与通关判定；若补在奇偶格，数字与奇偶要求同时保留。
- 补出的数字先用琥珀外圈提示位置，之后以普通数字线索显示。重开保留；退出重进、刷新或切关恢复原始关卡。补数不写回关卡文件，也不存档。
- 没有可补数字时提示尝试「指路」。

**指路**

- 当前无路径：指出合法起点（有 `1` 就指它；否则指解的真实起点）。
- 当前有路径且与唯一解的前缀一致：指出下一步。
- 当前有路径但已偏离唯一解：高亮最后一个正确格，压暗错段；点高亮格即可一次退回。若起点就错了，提示重开。
- 竖直切面：无限次、无广告。
- 上线：每天 1 次免费，之后激励视频。

**存档**

本地，键前缀 `mode:01-number-stroke`。存 `clearedId[]`、`currentId`。不存半途路径。不得读写其他玩法的桶。

高对比（冲突改成红底+斜纹）读壳的设置项，本玩法视图遵守即可。

---

## 11. 设计边界

V1 只做主规则（§4）。明确不做，留给后续版本或其它玩法：

- 对角邻接、斜走、传送、单向边
- 用户造关、关卡分享
- 计时、体力、分数

关卡、命名、视觉、音效全部原创，不使用第三方题库或素材。教学关按教学节拍手做（§7.1）。

---

## 12. 技术

全部落在 `modes/01-number-stroke/` 内。不要把本玩法的 Board / 邻接 / 求解器放到 `shared/` 或其它 `modes/`。

| 项 | 决定 |
|---|---|
| 竖直切面 | `web/` 单页，手机浏览器可玩，不经过壳首页 |
| 正式工程 | Cocos Creator 3.x，场景与脚本在 `assets/modes/01-number-stroke/` |
| 逻辑 | 纯 TypeScript，与渲染解耦。同一套规则跑在 `web/` 和 Cocos |
| 求解器 | `tools/solver.ts`，只服务本玩法 |
| 关卡 | `levels/*.json`，见 §8.3 |

核心代码模块（`src/`）：

- `model`：Cell、Board、Path、clue/conflict
- `rules`：邻接、合法下一步、过关判定
- `input`：手势 → 命令（Start / Append / Rewind / Reset）
- `solver`：枚举唯一解
- `clue-hint`：从唯一解选择待解区间的中间数字
- `view`：格、短边、数字、冲突、过关动画

对壳只暴露玩法入口 `id + mount/unmount`，见产品文档。

---

## 13. 竖直切面（做完才能说“玩法成立”）

可玩标准，全部要在真机或浏览器里点过：

1. 1-1 到 1-4 能独立教会滑动、走完、撤销、大格计 1 步。
2. 1-5 到 1-8 需要先想再画，不是闭眼滑。
3. 冲突态肉眼可辨，撤销后恢复。
4. 有线索 `1` 时，点其他格起手无效。
5. 无线索 `1` 的样例关至少 1 个（可放在 VS 附录关，不进前 12）。
6. 过关自动进下一关，进度刷新后还在。
7. 求解器对 VS 全部关断言 `paths.length === 1`。
8. 提示在偏离解时高亮分叉，不继续给错下一步。

VS 不做：广告、IAP、每日、动画角色、换皮、关卡编辑器 UI。

---

## 14. 里程碑

| 阶段 | 交付 |
|---|---|
| M0 | 本 GDD 锁定 |
| M1 | 规则库 + 求解器 + 1-1～1-4 可玩 |
| M2 | 1-1～1-12 + 输入手感 + 存档 |
| M3 | 再 32 关（生成+人工验收）+ 选关 |
| M4 | 迁 Cocos 本玩法场景，真机跑 VS 清单。不负责接其它玩法 |

M1 结束时如果 1-4 的“大格只计一步”教不会，先改教学盘，再加内容。

---

## 15. 关键决定

1. **关卡与资源全原创。** 不使用第三方题库或素材。
2. **大格是一等公民，不是皮肤。** 面积不影响步数，只影响邻接。这是和普通一笔画的分界。
3. **解必须唯一。** 休闲 puzzle 靠“想明白就过”，不靠多种走法碰运气。
4. **允许画错，不允许锁死。** 冲突标红，撤销和重开永远在。
5. **无计时、无分、无体力。** 会话长度由关卡大小控制。
6. **先 Web 规则原型，再 Cocos。** 玩法成立之前不上引擎装饰。
7. **V1 不加第二套机构。** 斜走、传送、单向边全部推迟。把 44 关的主规则打满。

---

## 16. 验收标准（玩法）

- 没玩过的人，不看文字，能在 1-4 结束前理解全部 V1 规则。
- 1-7 开始出现“停下来看”的瞬间，而不是滑完才发现错。
- 任意关在提示关闭时仍可人解，不依赖穷举。
- 同一关重开 10 次，手势与判定稳定，无幽灵邻接、无双触追加两步。

---

## 17. 已关闭的问题

- 要不要做成 2048 / 合成数字？不要。本玩法就是顺序一笔画。
- 要不要 V1 就上差异化机构？不要。先证明主规则。

## 18. 留给实现的缺口

- 本玩法对外名称是否就用「数字一笔 / Number Stroke」，上架前再定。产品总名称另定。
- 主色的最终值（蓝紫只是 VS 默认）。
- M3 的 32 关是全手做还是生成后人工改，看 M2 手感再定。
- 本玩法的 `src/`、`tools/`、`web/` 在 M1 才建。Cocos 场景在 M4 才建。