# 连连气球 · Cocos Creator 接入

当前交付是可玩的 Web 畅连版，以及同源 TypeScript 核心和 Creator 球槽组件。组件已使用本机 **Creator 3.8.8 的真实 cc.d.ts** 检查；Cocos 场景、手机原生包尚未运行验收。

## 导出与球槽

```bash
npm run cocos:check
npm run cocos:export -- /你的工程/assets/modes/02-connect-1234
```

默认生成 `cocos/export/02-connect-1234/`，每次重新生成，包含当前核心和 `adapters/Connect1234Board.ts`。自定义导出只写文件，不删除已有工程文件；从 v1 升级时建议导入新目录。JSON 常量导出为 TypeScript 数据模块，减少对宿主打包方式的依赖。

1. 创建本玩法 2D 场景，Canvas 建议 720 × 1280。
2. 创建 `Board`，添加 `UITransform`，尺寸例如 640 × 740；挂 `Connect1234Board`。
3. 设置 `seed`，默认 1234。没有关卡编号。
4. 球槽添加矩形 Mask 裁掉顶部进入的气球；背景、顶栏、能量条和工具按钮在宿主 UI 搭建。

逻辑坐标 **360 × 416，左上原点，Y 向下**。组件用 `UITransform.convertToNodeSpaceAR` 转换触摸，等比缩放并兼容任意锚点。只接受一根手指，触摸取消不提交；弹窗或切后台时禁用 Board 组件以取消当前手势。

## 方法与事件

| 方法 | 行为 |
|---|---|
| `startNew(seed?)` | 新开畅玩局，省略种子时使用当前时间 |
| `retry()` | 用相同种子重新开始 |
| `undo()` | 撤销上一操作，含补球、彩虹和微风 |
| `showHint()` | 显示可以实际滑出的提示链 |
| `shuffle()` | 免费微风重排并播放掉落 |
| `snapshot()` | 完整、可序列化状态副本 |

在宿主组件 `start` 中订阅并主动读取初始 `snapshot()`，避免错过 Board 的 `onLoad` 事件：

```ts
board.on('balloon-hud', ({ snapshot, canUndo, busy, fever }) => {
  // 分数、最大数字、能量、剩余双倍次数、queue 前 3 项；busy 时禁用工具。
});
board.on('balloon-reaction', (stage, doubled) => {
  // 每段合成的浮字/短音：stage.points、stage.index、stage.created。
});
board.on('balloon-settled', (result, snapshot) => {
  // 更新本地纪录；result.feverStarted 提示下一次开始双倍。
});
```

`balloon-merge` 在整次操作开始发出完整 `FlowResult`，含按序的 `beats`。不发过关或失败事件，不自动弹结算页。

## 规则、显示与存档

- `FlowGame.commit(ids)` 同步计算最终稳定状态，返回 `merge → fall → merge…` 时间线。`FlowAnimation` 按毫秒重放，无 DOM 或帧率依赖。
- `FlowResult.stages` 是所有合成段；`beats` 是真实播放顺序；最终盘面读 `result.supply.balls` 或 `game.balls`。`result.balls` 是最后一次合成后、最终补球前的盘面。
- 数字预告先兑现再补后续袋；掉落物理与自动接力不由宿主帧率决定。
- `view.ts` 的椭圆、路径、文字指令映射到 Graphics + Label。Label 节点池复用，支持数字描边；发布时可改成气球 Sprite + Label 池。
- `record.ts` 与 `StoragePort` 适配 `sys.localStorage`，键为 `mode:02-connect-1234:balloons-v2`。记录最高分、最大数、连消、放飞和声音设置，不保存中途局面。

```ts
import { sys } from 'cc';
import { loadRecord, recordRound, saveRecord } from './src/record';
const storage = {
  read: (key: string) => sys.localStorage.getItem(key),
  write: (key: string, value: string) => sys.localStorage.setItem(key, value),
};
const record = loadRecord(storage);
// 每次 balloon-settled：recordRound(record, snapshot.stats); saveRecord(storage, record);
```

## 性能与后续验收

最多 24 球；稳定时仅绘制，提交时试算少量落点。所有补给随机搜索有上限。测量脚本输出本机提交耗时，见 [QA](QA.md)；真机需重新测量，必要时将供给候选计算移入宿主分帧任务，同时保持同一随机序列。

不要直接换成帧率驱动的 Box2D 落点再复用当前数据假定；更换物理后需重新验证邻接、补给和手势路线。

```bash
npm run check
COCOS_TYPES=/路径/cc.d.ts npm run cocos:check
```

移植阶段剩余：Creator 实际场景、Mask 与安全区、音频、减少动态效果配置、前后台生命周期、Android/iOS 与目标小游戏平台触摸及性能验收。