NumberSwipe_New/modes/02-connect-1234/docs/archive-v1/HANDOFF.md

历史存档：关卡版 v1，已由连消畅玩版替换。当前规则见 GDD。

连号花园 · Cocos Creator 接手说明

当前交付边界

Web 版已完成十关、自由模式、动画、音效、提示、撤销、打乱、结算与本地进度。Cocos 交付的是 可导出的同一套核心代码 + 球槽组件；已经用本机 Creator 3.8.8 的真实 cc.d.ts 通过类型检查，尚未在 Creator 场景内完成运行验收。

后续移植需要在 Cocos 场景搭建顶栏、目标、按钮、选关和结算面板，绑定本文列出的事件。HTML/CSS 不作为游戏逻辑带入引擎。

1. 导出

在 modes/02-connect-1234 执行：

npm run cocos:export

输出 cocos/export/02-connect-1234/。将整个目录复制到 Creator 项目的 assets/modes/02-connect-1234/。也可显式指定输出路径：

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 节点监听：

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 实现：

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. 检查

npm run check
npm run cocos:check

cocos:check 自动寻找 macOS /Applications/Cocos/Creator/ 已安装版本，也可提供声明文件路径：

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

Creator 内还需验收：实际场景字体、触摸坐标、Mask、UI 安全区、音频、Android/iOS 原生包，以及微信等目标平台的生命周期。

参考接口

• Cocos 3.8 节点触摸事件
• UITransform 坐标转换
• Graphics 图形接口

实现及类型检查以本机 Creator 3.8.8 的声明文件为准。