初始提交：三玩法 Web 原型与设计文档
- 玩法一 数字一笔：规则库、求解器、26 关、竖屏触摸 Web 原型、测试 - 玩法二 连连气球：连消畅玩版核心、Web 原型、Cocos 球槽组件与导出脚本 - 玩法三 六边一笔：规则库、求解器、10 关 + 转墙实验包、Web 原型、测试 - 产品文档、UI 设计规范、各玩法 GDD / HANDOFF - 文档移除全部外部参考作引用；删除玩法二 v0 旧稿
This commit is contained in:
cabinw
@@ -0,0 +1,67 @@
|
||||
> 历史存档：关卡版 v1，已由连消畅玩版替换。当前规则见 [GDD](../GDD.md)。
|
||||
|
||||
# 连号花园 · 玩法二实现规格
|
||||
|
||||
2026-09-15：按本轮需求，从最初的无尽分数设计演化为 **10 关挑战 + 自由生长**。本文件是 v1 规则。
|
||||
|
||||
## 核心规则
|
||||
|
||||
- 圆球物理堆积；相邻圆心距 ≤ 半径之和 × 1.35。
|
||||
- 单指按住球，连接至少 3 个严格连续数字；升序、降序均合法，不能换向或重复用球。
|
||||
- 滑回上一颗撤回一步；快速滑动分段采样；触摸取消、窗口失焦不会提交合成。
|
||||
- 松手合成 `max + 1`，结果落在链尾；计分 `100 × 新数字 × 链长`。
|
||||
- 球半径 `min(82, 22 + 6 × (n−1))`，保留变大的空间压力；高数封顶保证自由模式仍可触摸。
|
||||
- 每次补到本关目标球数，面积最多占槽的 59%；物理稳定后才接收下一次操作。下落期间顶部开放，稳定收尾加入顶部约束，保证所有球可见且可触摸。
|
||||
- 无计时，非法手势不扣步。挑战每次有效合成消耗一步，所有目标达成即过关（最后一步先检查胜利）。
|
||||
- 没有合法链时允许撤销或使用本关唯一一次打乱；步数用尽可撤销或重试。
|
||||
|
||||
## 原创演化
|
||||
|
||||
- **固定种子与补球队列**：同一关重试能复盘，撤销连随机状态一并恢复。
|
||||
- **10 关目标制**：三连、倒序、四连、双目标、造大数逐步教学；有限步数，不限思考时间。
|
||||
- **容错**：免费提示、连续撤销、每关一次免费打乱。打乱保留球的数字、不耗步；无可行重排不扣次数。
|
||||
- **提示**：开局及沿标准解操作时显示经验证的下一步；偏离后寻找当前合法链，不保证整局最优。
|
||||
- **星级**：不打乱且在标准解步数以内为 3 星；标准步数 +2 以内为 2 星，其余通关为 1 星。提示、撤销不扣星。
|
||||
- **自由生长**：保留无尽分数循环，用掉落权重抽样，无关卡目标和步数上限。
|
||||
|
||||
## 10 关
|
||||
|
||||
完整配置、种子、补球队列、通关轨迹见 [campaign.json](../levels/campaign.json)。
|
||||
|
||||
| 关 | 名称 | 主要训练 | 目标 | 步数 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | 初芽 | 三连松手 | 合成 4 | 3 |
|
||||
| 2 | 回转 | 降序与落点 | 倒序合成一次 | 4 |
|
||||
| 3 | 伸展 | 长链 | 一次连 4 颗 | 5 |
|
||||
| 4 | 双生 | 材料预留 | 合成两颗 5 | 6 |
|
||||
| 5 | 丰收 | 长链得分 | 6,500 分 | 7 |
|
||||
| 6 | 抽叶 | 两个目标 | 合成两颗 6，四连 | 8 |
|
||||
| 7 | 繁枝 | 大球与落点 | 合成 7 | 9 |
|
||||
| 8 | 花径 | 弯曲长链 | 五连，14,000 分 | 10 |
|
||||
| 9 | 并蒂 | 连续筹备 | 合成两颗 7 | 12 |
|
||||
| 10 | 满园 | 综合挑战 | 合成 8，22,000 分 | 14 |
|
||||
|
||||
标准解由有界搜索找到并回放验算，不宣称唯一解或最优解。自动验证证明可通关，实际玩家难度仍可继续调参。
|
||||
|
||||
## UI 与触摸
|
||||
|
||||
- 对外名称「连号花园」，奶油纸色、鼠尾草绿、柔和彩球；6 以上长叶，8 以上小花。
|
||||
- 竖屏从上到下：品牌/声音/帮助 → 关卡入口 → 目标与步数 → 球槽 → 当前连线预览 → 撤销/提示/打乱/重来。
|
||||
- 数字在球心，颜色不参与判定。按钮触摸区至少 44px。
|
||||
- 适配安全区、320px 窄屏和横屏；球槽维持逻辑宽高比，短屏允许页面滚动，槽内禁止浏览器拖动。
|
||||
- 连线显示将生成的新数和分数；合成收拢、下落、得分浮字、过关结果；支持关闭音效与减少动态效果。
|
||||
- 选关底部面板，完成后解锁下一关；末关展示整套成绩并可转自由生长。
|
||||
|
||||
## 技术边界
|
||||
|
||||
`src/` 仅使用 ES2020 标准库；第二份 tsconfig 排除 DOM 和 Node 类型，持续证明无平台依赖。
|
||||
|
||||
- `game / rules / physics / random`：确定性状态机、规则、固定步长圆形物理。
|
||||
- `input`：平台无关手势状态机。
|
||||
- `goals / progress / levels`：目标、存档数据与关卡。
|
||||
- `view`：输出基础绘制指令，由 Canvas 或 Cocos Graphics/Label 适配。
|
||||
- `solver`：离线设计搜索、运行时轻量提示。
|
||||
- `web/`：浏览器输入、Canvas、音效、HTML 界面与本地存储。
|
||||
- `cocos/`：Creator 3.x 场景接入组件示例，迁移说明见 HANDOFF。
|
||||
|
||||
所有代码与玩法一、三隔离；不引入 React、DOM 规则、第三方物理引擎、服务端或远程素材。
|
||||
@@ -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 的声明文件为准。
|
||||
@@ -0,0 +1,60 @@
|
||||
> 历史存档：关卡版 v1，已由连消畅玩版替换。当前规则见 [GDD](../GDD.md)。
|
||||
|
||||
# 验证记录
|
||||
|
||||
日期：2026-09-15。当前实现的验证范围如下；未将浏览器触摸模拟称为实体手机测试。
|
||||
|
||||
## 自动检查
|
||||
|
||||
`npm run check` 全部通过：
|
||||
|
||||
- 两套 TypeScript 检查通过，其中 `src/` 不含 DOM / Node 类型。
|
||||
- **23 项测试**通过：规则、升降序、拒绝非法链、落点、最后一步成功、确定性重试、撤销、快速划线、取消、打乱、死局、失败、存档容错、十关触摸路线、帧率无关动画。
|
||||
- **10 / 10 关**使用固定种子逐步回放通过；验证同时经过 `Gesture`，避免“规则上合法、实际划线无法选中”的假解。
|
||||
- **1,225 个稳定盘面**通过边界与圆形重叠检查，含 **1,046 次随机合成**；最大数值穿透 **0.772 逻辑像素**（验收阈值 2px）。随机自由局自然结束；这批样本中最长连续局为 18 次合成。
|
||||
- 所有挑战关的开局与补球数字都在 1–4，最终通过正常合成得到 8。
|
||||
- 生产构建成功，JS 约 **33 KB**（未 gzip），不包含开发观察端口。
|
||||
- 独立 `release/` 正式包在端口 8003 实际完成第一关触摸合成（1,200 分，余 2 步），确认无开发观察端口，并已清理测试成绩、恢复第一关开局。见 [production.json](../qa/production.json)。
|
||||
|
||||
详细关卡逐步数字、球 ID、分数、步数与压力检查统计见 [validation.json](../qa/validation.json)。搜索给出的是一条可行路线，非唯一解、非最优解证明。
|
||||
|
||||
## 浏览器触摸验收
|
||||
|
||||
Ego Chromium，390 × 844 移动视口，使用 CDP `Input.dispatchTouchEvent` 产生浏览器输入：
|
||||
|
||||
- 从 **第 1 关实际连续游玩到第 10 关**，没有直接修改分数、盘面或过关状态。
|
||||
- 验证两颗松手不扣步、TOUCH_CANCEL 不提交、滑回上一颗撤回。
|
||||
- 确认十关依次解锁、最终结果为 10 / 10、存档记录 30 / 30 星。
|
||||
- 页面错误和未处理 Promise 拒绝记录为 **0**。
|
||||
- 后续刷新验证成绩保留；实际点按钮验证撤销和重走完全一致、打乱不扣步且保留数字、撤销恢复打乱库存。
|
||||
- 自由模式实际完成合成且步数保持无限；帮助面板可用 Escape 关闭。
|
||||
- 抽取动画为跨平台模块后，再次通过浏览器验证合成、撤销、重走和打乱。
|
||||
|
||||
结果见 [browser.json](../qa/browser.json)、[layout.json](../qa/layout.json)。`tools/browser-*.mjs` 是本次验收脚本，使用 `GARDEN_SPACE` 指定当前已有的 Ego QA 空间、`GARDEN_QA_DIR` 指定输出目录；应使用独立测试存档，先跑通关脚本再跑布局脚本。
|
||||
|
||||
## 尺寸检查
|
||||
|
||||
| 视口 | 结果 |
|
||||
|---|---|
|
||||
| 320 × 568 | 无横向溢出；页面高 650px，可纵向滚动触及底栏 |
|
||||
| 360 × 740 | 完整布局，主要按钮 ≥ 44px |
|
||||
| 390 × 844 | 完整布局，触摸通关主测试尺寸 |
|
||||
| 430 × 932 | 完整布局，主要按钮 ≥ 44px |
|
||||
| 844 × 390 | 横屏仍可操作，可纵向滚动 |
|
||||
| 1280 × 900 | 居中竖屏游戏面板与桌面背景 |
|
||||
|
||||
截图：[开局](../qa/mobile-initial.png) · [后段关卡](../qa/mobile-level8.png) · [帮助](../qa/mobile-help.png) · [选关](../qa/mobile-level-select.png) · [全通关](../qa/mobile-all-clear.png) · [桌面](../qa/desktop.png)。
|
||||
|
||||
## Cocos 迁移检查
|
||||
|
||||
`npm run cocos:check` 通过：
|
||||
|
||||
- 生成独立的 Creator 导入目录。
|
||||
- 使用本机 **Cocos Creator 3.8.8 的真实 `cc.d.ts`** 检查核心、数据与适配组件，非手写模拟类型。
|
||||
- 球槽坐标转换、Graphics、Label、触摸 API 均通过类型检查。
|
||||
|
||||
**仍需后续移植阶段完成**：Creator 场景实际运行、Cocos UI 面板搭建、原生 Android/iOS 与目标小游戏平台验收。当前不宣称这些工作已完成。
|
||||
|
||||
## 难度判断的范围
|
||||
|
||||
难度梯度由教学目标、解的步数、容错余量、长链和多轮合成要求制定，已验证全部关卡可通关。尚未做多人试玩统计，平均通关耗时、提示使用率、玩家卡关分布需要后续试玩采样。
|
||||
Reference in New Issue
Block a user