NumberSwipe_New/README.md

number-swipe

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

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

玩法	目录	一句话	状态
一 · 数字一笔	modes/01-number-stroke	矩形拼板一笔画，大格只计一步，数字 / 奇偶线索必须踩对	Web 竖屏原型可玩，26 关（入门 10 + 进阶 10 + 奇与偶 6），有单文件试玩版
三 · 六边一笔	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+。两个玩法的命令完全一致，只是目录和端口不同。

# 玩法一 · 数字一笔（默认端口 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）：

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/design.md / design.html	UI 设计规范与设计师样张
modes/01-number-stroke/docs/GDD.md	玩法一规格：规则、交互、反馈、关卡语言、求解器、竖直切面、验收
modes/01-number-stroke/docs/HANDOFF.md	玩法一交接：实现细节、与 GDD 的偏差、已知问题、Cocos 迁移步骤
modes/03-hex-walls/docs/GDD.md	玩法三规格，附录 A 为转墙规则
modes/03-hex-walls/docs/HANDOFF.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 关。