初始提交：三玩法 Web 原型与设计文档

- 玩法一数字一笔：规则库、求解器、26 关、竖屏触摸 Web 原型、测试 - 玩法二连连气球：连消畅玩版核心、Web 原型、Cocos 球槽组件与导出脚本 - 玩法三六边一笔：规则库、求解器、10 关 + 转墙实验包、Web 原型、测试 - 产品文档、UI 设计规范、各玩法 GDD / HANDOFF - 文档移除全部外部参考作引用；删除玩法二 v0 旧稿
2026-09-16 14:30:59 +08:00
commit 8026e4628d
169 changed files with 22162 additions and 0 deletions
@@ -0,0 +1,114 @@
+> 历史存档：关卡版 v1，已由连消畅玩版替换。当前规则见 [GDD](../GDD.md)。
+
+# 连号花园 · Cocos Creator 接手说明
+
+## 当前交付边界
+
+Web 版已完成十关、自由模式、动画、音效、提示、撤销、打乱、结算与本地进度。Cocos 交付的是 **可导出的同一套核心代码 + 球槽组件**；已经用本机 Creator 3.8.8 的真实 `cc.d.ts` 通过类型检查，尚未在 Creator 场景内完成运行验收。
+
+后续移植需要在 Cocos 场景搭建顶栏、目标、按钮、选关和结算面板，绑定本文列出的事件。HTML/CSS 不作为游戏逻辑带入引擎。
+
+## 1. 导出
+
+在 `modes/02-connect-1234` 执行：
+
+```bash
+npm run cocos:export
+```
+
+输出 `cocos/export/02-connect-1234/`。将整个目录复制到 Creator 项目的 `assets/modes/02-connect-1234/`。也可显式指定输出路径：
+
+```bash
+npm run cocos:export -- /你的工程/assets/modes/02-connect-1234
+```
+
+导出时仅将 JSON 导入替换成生成的等价 TypeScript 数据模块，避免依赖 Creator 对 JSON module 的打包行为。规则、物理、手势、绘制指令、动画、目标、存档结构保持同一份源码。
+
+不要手动修改导出目录；改 `src/`、`levels/` 或 `cocos/Connect1234Board.ts`，重新导出即可。
+
+## 2. 创建球槽
+
+1. 新建本玩法的 2D 场景，Canvas 设计分辨率建议 **720 × 1280**。
+2. 在 Canvas 下创建 `Board` 节点，加 `UITransform`，尺寸可用 **640 × 740**。
+3. 将导出包的 `adapters/Connect1234Board.ts` 挂到 `Board`。组件自动创建 Graphics 与复用的 Label 节点。
+4. 在 Inspector 设置 `levelNumber` 为 1–10；运行后即可对球槽进行触摸连号。
+5. 为 Board 的绘图区域配置矩形 Mask，裁掉从顶部掉入的球。背景颜色、圆角容器由场景美术完成。
+
+核心坐标为 **360 × 416，左上角原点，Y 向下**。适配组件自动等比缩放并用 `UITransform.convertToNodeSpaceAR` 转换触摸坐标，不需要改变球的半径、物理或邻接算法。
+
+## 3. 绑定 UI
+
+组件公开：
+
+| 方法 | 行为 |
+|---|---|
+| `loadLevel(number)` | 加载第 1–10 关 |
+| `retry()` | 按固定种子重开当前关 |
+| `undo()` | 撤回一次合成或打乱 |
+| `showHint()` | 显示提示连线 |
+| `shuffle()` | 每关一次重排，数字保留、不扣步 |
+| `snapshot()` | 获取完整状态副本 |
+
+在 Board 节点监听：
+
+```ts
+board.on('garden-hud', ({ level, snapshot, goals, canUndo }) => {
+  // 刷新标题、分数、步数、目标、工具按钮。
+});
+board.on('garden-merge', (result) => {
+  // 播放音效、振动、得分浮字。球槽自身已播放合成和下落动画。
+});
+board.on('garden-result', (status, snapshot) => {
+  // won: 成功；lost: 步数用完；stuck: 无合法链。
+  // 核心不会自动弹面板或跳关，由壳/UI 决定。
+});
+```
+
+玩法切场景时由组件生命周期解绑触摸；只接受一根活动手指，TOUCH_CANCEL 会取消手势。宿主弹模态面板或进后台时应禁用 Board 组件，触发取消。
+
+组件示例接入的是挑战模式。自由模式的逻辑已经在 `new Game(level, true)` 内实现，按 Web 的入口方式补一个场景按钮即可；其随机开局应确保至少有一条合法链。
+
+## 4. 存档和音效
+
+`src/progress.ts` 仅接受 `StoragePort` 接口。Cocos 实现：
+
+```ts
+import { sys } from 'cc';
+const storage = {
+  read: (key: string) => sys.localStorage.getItem(key),
+  write: (key: string, value: string) => sys.localStorage.setItem(key, value),
+};
+```
+
+存档键 `mode:02-connect-1234:v1`，保存各关最高分/星级及最高数字。不存中途盘面。音效使用 Cocos `AudioSource`，订阅 `garden-merge`；Web 的音效是本地合成的短音，不需要下载音频素材。
+
+## 5. 物理与性能
+
+- 继续使用核心固定步长圆形分离物理，可保证 Web 与 Cocos 的固定关卡解一致。
+- `Game.commit` 先算稳定状态；`MergeAnimation` 负责重放收拢和物理过程，宿主只传入毫秒时间。
+- 核心不会在每个显示帧重算关卡。最多 18 个球，稳定盘面冻住，操作时不会追着移动的球连线。
+- Graphics 适配器是接入示例；发布时可将彩球换为 Sprite + Label 预制体池，保留相同球 ID 和坐标。无需变更规则。
+- 如果未来换 Box2D，请保留逻辑判定盘面与显示物理解耦，或重新验证全部关卡。直接替换积分器可能改变邻接和落点。
+
+## 6. 检查
+
+```bash
+npm run check
+npm run cocos:check
+```
+
+`cocos:check` 自动寻找 macOS `/Applications/Cocos/Creator/` 已安装版本，也可提供声明文件路径：
+
+```bash
+COCOS_TYPES=/路径/cc.d.ts npm run cocos:check
+```
+
+Creator 内还需验收：实际场景字体、触摸坐标、Mask、UI 安全区、音频、Android/iOS 原生包，以及微信等目标平台的生命周期。
+
+## 参考接口
+
+- [Cocos 3.8 节点触摸事件](https://docs.cocos.com/creator/3.8/manual/en/engine/event/event-node.html)
+- [UITransform 坐标转换](https://docs.cocos.com/creator/3.8/api/en/class/UITransform)
+- [Graphics 图形接口](https://docs.cocos.com/creator/3.8/api/en/class/GraphicsComponent)
+
+实现及类型检查以本机 Creator 3.8.8 的声明文件为准。