cabinw
8026e4628d
- 玩法一 数字一笔：规则库、求解器、26 关、竖屏触摸 Web 原型、测试 - 玩法二 连连气球：连消畅玩版核心、Web 原型、Cocos 球槽组件与导出脚本 - 玩法三 六边一笔：规则库、求解器、10 关 + 转墙实验包、Web 原型、测试 - 产品文档、UI 设计规范、各玩法 GDD / HANDOFF - 文档移除全部外部参考作引用；删除玩法二 v0 旧稿
115 lines
5.2 KiB
Markdown
115 lines
5.2 KiB
Markdown
> 历史存档：关卡版 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 的声明文件为准。
|