NumberSwipe_New/modes/01-number-stroke/README.md

# 玩法一 · 数字一笔

按数字顺序，一笔画走完盘面上每一格。大格只计一步。

本目录自包含：规格、关卡、规则代码、求解器和 Web 原型。不要依赖 `modes/02` 或 `modes/03`。壳需要的东西通过 `shared/` 的玩法入口对接，见 [`docs/PRODUCT.md`](../../docs/PRODUCT.md)。

关卡、资源、文案全部原创，不使用第三方题库或素材。

## 状态

M1/M2 已达：竖屏触摸 Web 原型可玩，三包 26 关全部经求解器断言唯一解，含 6 关「奇与偶」体验包；存档、补数字 / 指路双提示、音效、振动齐全。68 个单元测试通过。下一步为试玩调校与 M4 迁 Cocos。

## 目录

| 路径 | 用途 |
|---|---|
| [`docs/GDD.md`](docs/GDD.md) | 本玩法规格（权威） |
| [`docs/HANDOFF.md`](docs/HANDOFF.md) | 交接文档：实现了什么、怎么实现、与 GDD 的偏差、待办与 Cocos 迁移顺序 |
| [`../../docs/design.md`](../../docs/design.md) | UI 设计规范（色彩 / 字阶 / 组件 / 动效）。`web/style.css :root` 与 `src/theme.ts` 由 `tests/theme.test.ts` 校验一致 |
| [`levels/pack-1-tutorial.json`](levels/pack-1-tutorial.json) | 第一包 10 关（教学） |
| [`levels/pack-2-advanced.json`](levels/pack-2-advanced.json) | 第二包 10 关（进阶，生成器产出 + 人工过目） |
| [`levels/pack-3-parity.json`](levels/pack-3-parity.json) | 第三包 6 关（奇与偶，每条奇偶线索都参与唯一性） |
| [`src/`](src/) | **纯 TS 规则层，零 DOM / 零 Cocos 依赖**。Web 与 Cocos 共用 |
| [`web/`](web/) | 浏览器原型：DOM / Canvas / PointerEvent / localStorage 粘合层 |
| [`tools/`](tools/) | 求解器命令行：全关卡校验、关卡设计辅助 |
| [`tests/`](tests/) | 规则层单元测试（node:test） |

`src/` 分层：

```
types.ts     关卡 JSON 结构
board.ts     Cell / Board：单位网格、四向邻接、共享边
clue.ts      数字 / 奇偶线索统一判定与显示文字
game.ts      对局状态机：Command → GameEvent（含 rewind 多步回退、reveal 补数字）
input.ts     手势语义：按下/移动/松手 + “当前压在哪个格” → Command
solver.ts    枚举满足线索的哈密顿路径、唯一解、提示（下一步 / 退回分叉）
clue-hint.ts 在尚未解开的数字区间补中间数，不替玩家画路线
layout.ts    盘面适配、格矩形、桥矩形、命中测试（带死区）
view.ts      BoardView：格/桥/数字/冲突/提示/过关动效，只调用 Painter
painter.ts   绘制原语接口（圆角矩形、圆、居中文字）
theme.ts     配色
progress.ts  存档（KeyValueStore 抽象，桶 mode:01-number-stroke）
levels.ts    关卡包解析
```

## 运行

```bash
cd modes/01-number-stroke
npm install
npm run dev        # 起本地服务 + 监听改动，终端会打印手机可访问的局域网地址
npm run build      # 打包到 web/dist/app.js，之后可直接双击 web/index.html
npm run build:standalone  # 导出项目根目录 releases/数字一笔-试玩版.html
npm run check      # 类型检查（含 src/ 无 DOM 校验）+ 单元测试 + 全关卡唯一解校验
```

`?dev=1` 解锁全部关卡并暴露 `window.__numberStroke` 调试句柄（自动化手势测试用）。
直接体验奇偶：`http://localhost:8000/?dev=1&level=3-1`。`level` 跳关参数仅在开发模式下生效；不清空已有存档。

**发给朋友测试**：运行 `npm run build:standalone`，发送生成的 [`数字一笔-试玩版.html`](../../releases/数字一笔-试玩版.html) 一个文件即可。脚本、样式、26 关数据与合成音效全部内置，无需安装或启动服务，可离线用浏览器打开。全部 26 关直接可选，无需解锁或添加参数；通关记录仍保存在试玩者的浏览器中。

关卡工具：

```bash
npm run validate            # 每关：连通、恰好 1 条满足线索的哈密顿路径
npm run validate -- 1-7     # 只看某关，并打印解
npm run design -- 1-7 --minimize          # 当前线索里哪些可删
npm run design -- 1-7 --suggest 3 --path a,b,c,...   # 给作者解找最少线索
npm run generate -- --seed 3 --out levels/pack-2-advanced.json   # 随机铺盘+作者解+挑线索，批量产关
```

选关页按包分区渲染，跨包线性解锁（2-1 需先过 1-10）；`web/main.ts` 顶部的 `packs` 数组登记包文件，加新包时往数组里加 import 即可。

## 第一包 · 10 关

每关只加一个旋钮（GDD §7）。线索数已按 §4.6 收到教学所需的最少。

| 关 | N | 教什么 | 大格 | 线索 |
|---|---|---|---|---|
| 1-1 | 3 | 滑动，邻格自动出步号 | – | 1 |
| 1-2 | 4 | 必须走完所有格 | – | 1, 4 |
| 1-3 | 5 | 走错可以退（第一次死路） | – | 1, 3 |
| 1-4 | 4 | 大格只算一步 | 2×2 | 1, 3 |
| 1-5 | 7 | 中段线索 | – | 1, 4 |
| 1-6 | 9 | 空洞：隔洞不相邻，先看终点再起手 | – | 1, 9 |
| 1-7 | 12 | 先推再画：三处分叉各需一次推理 | – | 1, 4, 8 |
| 1-8 | 11 | 2×2 当枢纽：6 个出口只能选远角 | 2×2 | 1, 8 |
| 1-9 | 11 | 横长条：b 紧挨 1 却是第 6 步，只能从长条下边进上边出 | 2×1 | 1, 6 |
| 1-10 | 14 | 小考：顶行直走只有 5 步，要借 2×2 垫一步；竖长条收尾 | 2×2 + 1×2 | 1, 6 |

GDD §7.1 的 12 关教学梯度压缩到 10 关：竖长条与“两个大格”并入 1-10；无线索 `1` 的关按 §7 留在第 13 关之后，本包不含。

## 第二包 · 10 关（进阶）

`tools/generate.ts` 自动生成（seed=43）+ 人工过目。面向已经会玩的人，三个设计原则（来自试玩反馈，已写进 GDD §4/§7/§8.2）：

- **难度的主旋钮是相邻线索的步号差**。每关开局固定「线索 1 + 4~7 步内的引导线索」，玩家先有起手方向；难度靠后面的差距拉开（包内最大差从 8 升到 16）。
- **大连块高频出现**：每关 2~3 个多单位格，`2×2` 在 7 关出现，`3×3` 在 2-2、2-4 出现。大连块只计 1 步但出口多，是推理的主战场。
- **格子可以是俄罗斯方块式异形**（L/I/S/T，随机旋转镜像）。异形格占 2~4 个单位格、仍只计 1 步，凹口让邻接关系更不规则；渲染上拼块连成一整块（单位矩形 + 延展接缝），与 `2×2` 观感一致。

| 关 | N | 大连块与异形 | 空洞 | 线索 | 步号差 |
|---|---|---|---|---|---|
| 2-1 | 16 | 异形×2 + 2×2 | – | 1, 7, 14 | 6/7/2 |
| 2-2 | 14 | **3×3** + 异形 | – | 1, 4, 12 | 3/8/2 |
| 2-3 | 18 | 异形×2 | 1 | 1, 4, 8, 16 | 3/4/8/2 |
| 2-4 | 15 | **3×3** | 1 | 1, 6, 15 | 5/9/0 |
| 2-5 | 16 | 2×2×2 + 异形 | – | 1, 6, 15 | 5/9/1 |
| 2-6 | 18 | 2×2×2 | 1 | 1, 4, 8 | 3/4/10 |
| 2-7 | 21 | 2×2 + 条 | – | 1, 7, 17 | 6/10/4 |
| 2-8 | 19 | 异形×2 | – | 3, 5, 15, 17 | 2/10/2/2 |
| 2-9 | 21 | 2×2 + 条 | – | 1, 7, 20 | 6/13/1 |
| 2-10 | 21 | 2×2 + 条 | – | 1, 5, 21 | 4/16/0 |

2-8 **无线索 1**（全游戏第一关）：起点也要自己找。

每关 JSON 里的 `teach` 字段存了生成参数与作者解（剧透，永不渲染）。想换一批：`npm run generate -- --seed <新种子> --out levels/pack-2-advanced.json`，然后 `npm run check`。

## 第三包 · 6 关（奇与偶）

「奇」要求走到该格时的步数为 1、3、5…，「偶」要求 2、4、6…。整块仍只计一步，数字与奇偶条件要同时满足。走过后显示实际步号并保留奇偶标记；走错可撤回，提示也考虑奇偶要求。

| 关 | 格数 | 内容 |
|---|---|---|
| 3-1 | 4 | 「偶」入门，借 2×2 调整步数 |
| 3-2 | 6 | 「奇」写在 3×3 上，整块只计一步 |
| 3-3 | 11 | 用奇数条件决定绕行方向 |
| 3-4 | 16 | 异形格上的「偶」＋「奇」＋数字线索 |
| 3-5 | 18 | 双异形、奇偶与中段数字共同推理 |
| 3-6 | 18 | 两个 2×2、两个「奇」，仅固定起点 1 |

3-2 为新盘，其余复用既有关卡的几何并重新设计线索（来源及作者解记在 `teach`）。每关唯一解；逐条删去任意奇偶条件都会出现多解，确保新规则有实际作用。此包先用于体验规则，难度手感仍待真人试玩。

关卡中写 `"parity": "odd"` / `"parity": "even"`，与同格 `clue` 互斥；可与 `shape` 或 `3×3` 共用。`npm run design -- 3-4 --minimize` 会同时检查数字和奇偶线索。现有随机生成器仍产出数字关，奇偶包采用人工配线索并用求解器筛选。

## 交互（已实现，对齐 GDD §5）

- 有线索 `1` 时只能从它起手，点别处 `1` 抖一下
- 按住滑到相邻未走格追加；点按或滑到任意已走格，直接撤掉该格之后的路径，不松手就能换方向继续画
- 松手保留路径；从末端按下继续；点末端旁的空格仍可追加；不相邻的空格忽略
- 快速滑动在两帧之间插值采样，避免漏掉中间格；直接落到历史格时优先回退。触屏死区收至 8%，鼠标维持 14%；只跟踪一个指针
- 踩错线索，或第 n 步走到预定数字 n 所在格以外的位置，立即让该格变红并轻晃，连接线保持紫色，不加叉号；本格要求不符时仍显示原数字 / 奇偶要求。原始数字与补出的数字都生效；退回后清除冲突。死路当前格抖动，不弹失败
- 补数字：优先当前尚未解开的数字区间，1～9 补 5；每次只给一个确定数字，遵守原来的奇偶规则。重开保留补数，退出重进则恢复原关卡
- 指路：无路径指起点；是解的前缀给下一步；已偏离则高亮分叉格并压暗错段，点高亮格即可直接回退
- 过关：路径提亮、按步序扫光，约 0.9s 后自动下一关；最后一关回选关

## 移植到 Cocos Creator

技术选型就是为这一步做的：

1. **`src/` 原样拷进 `assets/modes/01-number-stroke/scripts/`。** 它用 `tsconfig.src.json`（`lib: ["ES2020"]`，无 DOM）编译通过；import 全部无后缀，符合 Cocos 模块规范（Cocos 不允许 `import './foo.ts'`）。
2. **Painter 换实现。** `web/canvas-painter.ts` 对应一个 `GraphicsPainter`：`fillRoundRect/strokeRoundRect/fillCircle` 用 `Graphics`，`text` 用一组按需复用的 `Label` 节点。`BoardView.draw()` 不用改。Cocos 的 y 轴向上，在 Painter 里翻一次 y 即可。异形格不用新原语：`layout.cellShapeRects()` 把拼块拆成单位矩形 + 接缝矩形，复用同一套 `fillRoundRect`。
3. **输入换事件源。** `Node.on(TOUCH_START/MOVE/END)` 把触点转成 Canvas 节点局部坐标 → `layout.hitTest()` → `PointerInput.down/move/up()`。插值采样那几行照搬 `web/main.ts`。
4. **存档换 store。** `Progress` 接收 `KeyValueStore`，Cocos 用 `sys.localStorage` 包一层。
5. **关卡 JSON 放 `resources/`**，`resources.load` 成 `JsonAsset` 后走同一个 `parsePack/loadPack`。
6. **HUD / 选关是 UI 节点。** 对应 `web/index.html` 里那几个元素：顶栏（返回、关号、剩余格）、字幕、底栏（重开、补数字、指路）、选关网格。
7. **音效**：`web/audio.ts` 是 WebAudio 合成；Cocos 用 `AudioSource` 播 4 段短音（step / conflict / cleared / reject），接口一致。
8. 每帧：`view.update(dt)` 放 `update(dt)`，`view.draw(painter)` 在 `isAnimating` 为真时清空 Graphics 重画。

不搬进 Cocos 的东西：`web/`、`tools/`、`tests/`（测试可以继续在 Node 跑，它们只依赖 `src/`）。