NumberSwipe_New/README.md

# number-swipe

多玩法休闲 puzzle（工作名，上架名未定）。目前两个玩法，都属于「顺序一笔画」路径推理：用一次滑动走遍盘面上每一格，预先写好的数字必须刚好在那一步踩到。两者几何与障碍不同，共用一个壳，规则代码彼此独立。

手机竖屏、单机、离线可玩；无计时、无体力、无分数。先做 Web 触摸原型验证玩法，再迁 Cocos Creator。

| 玩法 | 目录 | 一句话 | 状态 |
|---|---|---|---|
| 一 · 数字一笔 | [`modes/01-number-stroke`](modes/01-number-stroke) | 矩形拼板一笔画，大格只计一步，数字 / 奇偶线索必须踩对 | Web 竖屏原型可玩，26 关（入门 10 + 进阶 10 + 奇与偶 6），有单文件试玩版 |
| 三 · 六边一笔 | [`modes/03-hex-walls`](modes/03-hex-walls) | 六边形一笔画，墙贴在边上挡住那一条邻接 | Web 竖屏原型可玩，10 关 + 转墙实验包 9 关 |

目录编号保留 `01` / `03`：曾有玩法二（连连气球），2026-09-16 放弃并移出仓库（历史在首个提交里）。编号同时是存档桶名和 Cocos 资源路径，不要重排。

---

## 两个玩法的共同规则

- **哈密顿路径**：每格恰好经过一次，只能走到相邻且未走过的格，第 `k` 步的格子显示数字 `k`。
- **线索**：部分格预写数字 `c`，走到时步号必须等于 `c`。线索可在中段；可以没有 `1`（起点未知）。
- **允许画错，不允许锁死**：踩错线索的格变红，不打断手势；随时沿原路撤销或一键重开；没有失败弹窗。
- **解唯一**：每一关发布前由求解器断言恰好 1 条满足全部线索的路径。
- **提示不带错**：无路径时指起点；路径是解的前缀时给下一步；已偏离时高亮分叉点让玩家退回，不继续往错路上填。
- **过关**：所有格走过且所有线索正确 → 短动效后自动下一关。

## 两个玩法的差异

| | 一 · 数字一笔 | 三 · 六边一笔 |
|---|---|---|
| 格子 | 轴对齐矩形（`1×1` 到 `3×3`）和俄罗斯方块式异形块，**整块只计 1 步** | 正六边形，一格一步，无大格 |
| 邻接 | 四向共边 | 六向共边（轴坐标 `q, r`） |
| 障碍 | 空洞 | 空洞 + **边墙**（有墙的两格视为不相邻）；实验：随步数旋转的转墙 |
| 额外线索 | 奇 / 偶（该格步号的奇偶性） | – |
| 难度主旋钮 | 大格出口多但只算 1 步；相邻线索的步号差 | 墙掐掉表面上的近路；墙贴在线索旁让第一步只剩一个方向 |
| 存档桶 | `mode:01-number-stroke` | `mode:03-hex-walls` |

玩法三不是玩法一的 DLC：几何、邻接、障碍都独立，两边各写一份规则代码，禁止互相 import。

---

## 仓库结构

```
number-swipe/
  README.md                       本文件
  docs/
    PRODUCT.md                    产品级约定：壳、隔离规则、玩法清单、里程碑
    design.md                     UI 设计规范：色彩令牌、字阶、组件、四档动效（玩法一为参考实现）
    design.html                   设计师版：色板、组件样张、可回放动效（离线双击可看）
  modes/
    01-number-stroke/             玩法一 · 数字一笔（自包含）
      docs/GDD.md                 规格（权威）
      docs/HANDOFF.md             交接：做了什么、怎么做、与 GDD 的偏差、待办、Cocos 迁移顺序
      levels/*.json               三个关卡包
      src/                        纯 TS 规则层（零 DOM / 零 Cocos 依赖）
      web/                        浏览器粘合层：DOM / Canvas / PointerEvent / localStorage
      tools/                      求解器命令行：校验、设计辅助、随机生成
      tests/                      规则层单元测试（node:test）
    03-hex-walls/                 玩法三 · 六边一笔（自包含，同样的分层）
      docs/GDD.md
      docs/HANDOFF.md
      levels/*.json
      src/  web/  tools/  tests/
  shared/                         壳：选玩法首页、设置、存档索引、广告位（尚无代码）
  releases/
    数字一笔-试玩版.html            玩法一单文件试玩版，离线可开
```

每个玩法目录都是一个独立的 npm 工程，有自己的 `package.json`、`tsconfig` 和 `node_modules`。

---

## 快速开始

需要 Node.js 20+。两个玩法的命令完全一致，只是目录和端口不同。

```bash
# 玩法一 · 数字一笔（默认端口 8000）
cd modes/01-number-stroke
npm install
npm run dev              # 本地服务 + 监听改动，终端打印手机可访问的局域网地址
npm run check            # 类型检查（含 src/ 无 DOM 校验）+ 单元测试 + 全关卡唯一解校验

# 玩法三 · 六边一笔（默认端口 8100）
cd modes/03-hex-walls
npm install
npm run dev
npm run check
```

其它脚本（两边都有）：

| 命令 | 作用 |
|---|---|
| `npm run build` | 打包到 `web/dist/app.js`，之后可直接双击 `web/index.html` |
| `npm run validate` | 逐关校验：连通、恰好 1 解（玩法三额外：第 3 关起去墙后不唯一、无冗余墙） |
| `npm run validate -- 1-7` | 只看某关并打印解 |
| `npm run design -- 1-7 --minimize` | 当前线索里哪些可删 |
| `npm run generate -- ...` | 随机铺盘 + 作者解 + 挑线索，批量产候选关 |

仅玩法一有 `npm run build:standalone`，导出 `releases/数字一笔-试玩版.html`：脚本、样式、26 关数据与合成音效全部内置，发一个文件给朋友即可离线试玩，全部关卡直接可选。

开发参数：URL 加 `?dev=1` 解锁全部关卡并暴露调试句柄（`window.__numberStroke` / `window.__hexWalls`）；玩法一支持 `&level=3-1` 直接跳关。

---

## 关卡

关卡全部是 JSON，运行时只做规则模拟，不存解；解由 `tools/validate.ts` 在发布前枚举并断言唯一。

**玩法一**（`modes/01-number-stroke/levels/`）

- `pack-1-tutorial.json` 入门 10 关：每关只加一个旋钮——滑动 → 走完 → 撤销 → 大格 → 中段线索 → 空洞 → 先推再画 → 2×2 枢纽 → 长条 → 小考。
- `pack-2-advanced.json` 进阶 10 关：生成器产出 + 人工过目。大连块高频、`3×3`、异形块，难度靠相邻线索的步号差拉开；2-8 是第一关无线索 `1`。
- `pack-3-parity.json` 奇与偶 6 关：格上写「奇」/「偶」要求步号奇偶，与数字线索互斥、可与大格共用；每条奇偶条件都参与唯一性。

**玩法三**（`modes/03-hex-walls/levels/`）

- `pack-1-tutorial.json` 教学 10 关：无墙两关 → 第一堵墙 → 墙贴在 `1` 旁 → 中段线索 → 空洞 + 两墙 → 陷阱格 → 综合 → 走廊 → 满花盘 4 墙。每关断言「去掉全部墙后解不唯一」，保证墙在干活。
- `pack-2-spinner.json` 转墙 9 关（实验）：绕顶点转的墙，每走一格顺时针转 120°。规则见玩法三 GDD 附录 A。

每关明细（格数、线索、去墙解数）见各玩法 README。

---

## 工程约定

隔离规则（详见 [`docs/PRODUCT.md`](docs/PRODUCT.md)）：

1. `modes/*` 之间禁止互相 import。规则、求解器、关卡、对局视图都属于玩法自己。
2. `shared/` 只放壳：玩法注册表、首页、设置、存档索引、广告位、通用皮肤。禁止出现过关判定、邻接、提示算法、关卡 JSON。
3. 存档按玩法 id 分桶，互不读写。
4. 壳看到的入口只有 `{ id, title, mount(root, ctx), unmount() }`；`ShellContext` 只给存档读写、音效、振动、返回首页。

分层约定（两个玩法一致，为迁 Cocos 设计）：

- `src/` 用 `tsconfig.src.json`（`lib: ["ES2020"]`）编译，**不能碰 DOM**，import 全部无后缀。这层原样拷进 Cocos 工程。
- 绘制走 `Painter` 接口（圆角矩形 / 多边形 / 圆 / 居中文字），Web 用 Canvas 实现，Cocos 换 `Graphics` + `Label` 池实现，`View.draw()` 不改。
- 输入走 `PointerInput.down/move/up()`，事件源可替换；存档走 `KeyValueStore` 抽象，Cocos 用 `sys.localStorage` 包一层。
- 视觉令牌三处一致：`web/style.css :root`、`src/theme.ts`、`docs/design.md`，由 `tests/theme.test.ts` 校验。

内容约定：关卡、美术、文案全部原创，不使用第三方题库或素材。

---

## 文档索引

| 文档 | 内容 |
|---|---|
| [`docs/PRODUCT.md`](docs/PRODUCT.md) | 产品结构、隔离规则、共享决策、里程碑 |
| [`docs/design.md`](docs/design.md) / [`design.html`](docs/design.html) | UI 设计规范与设计师样张 |
| [`modes/01-number-stroke/docs/GDD.md`](modes/01-number-stroke/docs/GDD.md) | 玩法一规格：规则、交互、反馈、关卡语言、求解器、竖直切面、验收 |
| [`modes/01-number-stroke/docs/HANDOFF.md`](modes/01-number-stroke/docs/HANDOFF.md) | 玩法一交接：实现细节、与 GDD 的偏差、已知问题、Cocos 迁移步骤 |
| [`modes/03-hex-walls/docs/GDD.md`](modes/03-hex-walls/docs/GDD.md) | 玩法三规格，附录 A 为转墙规则 |
| [`modes/03-hex-walls/docs/HANDOFF.md`](modes/03-hex-walls/docs/HANDOFF.md) | 玩法三交接 |
| [`shared/README.md`](shared/README.md) | 壳的边界：能放什么、不能放什么 |

---

## 状态与路线

| 阶段 | 状态 |
|---|---|
| 各玩法 M1/M2：规则库 + 求解器 + 可玩原型 + 存档 / 提示 / 音效 / 振动 | 两个玩法均已达成 |
| 真人试玩调校：手势死区、教学梯度、关卡难度手感 | 待做，需要 3～5 个没玩过的人 |
| 壳：选玩法首页、设置、存档索引 | 未开始（两个玩法原型都已可玩，可以开工） |
| M4：迁 Cocos Creator 3.x，各玩法独立场景，资源放 `assets/modes/<id>/` | 未开始，迁移顺序写在各 HANDOFF |

已知的规格与实现偏差（各 HANDOFF §3 有全表）：两份 GDD 的教学关数与内容计划（玩法一 12 关 / 44 关，玩法三 8 关 / 32 关）仍是早期目标值，实际为 10 关 / 26 关与 10 关。