> 历史存档：关卡版 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 的声明文件为准。