Gem Cascade 是一个可在浏览器中直接运行的单机三消游戏。当前代码对应 Phase 1 MVP：本地、离线、可静态部署，不依赖服务器、数据库、账号系统或联网同步。
- 8 x 8 棋盘。
- 30 步计分模式；每次有效交换消耗 1 步，无效交换会回退且不消耗步数。
- 普通宝石共有 6 种颜色，并已按颜色绑定不同形状，便于区分：
- red：圆形
- blue：方形
- green：菱形
- yellow：三角形
- purple：六边形
- orange：五角星
- 横向或纵向 3 个及以上同色宝石会消除。
- 4 连生成火箭宝石：横向 4 连生成横向火箭，纵向 4 连生成纵向火箭。
- 5 连生成彩虹宝石。
- T 型或 L 型匹配生成炸弹宝石。
- 消除后会下落、补充新宝石，并继续处理自动连锁。
- 得分规则为：本轮唯一消除格数 x 10 x 当前连锁倍率。
- React HUD 显示状态、分数、最高分、剩余步数、图标化声音开关和图标化 Help 入口。
- 浏览器/设备首选语言以
zh开头时显示简体中文，其他语言显示英文；Help 说明也会同步切换。 - LocalStorage 保存最高分和声音开关。
普通宝石使用颜色 + 形状双重编码，特殊宝石在普通形状上叠加标记：
- 横向火箭：白色横条。
- 纵向火箭：白色竖条。
- 炸弹：深色核心与橙色外圈。
- 彩虹宝石：蓝色外圈与红色核心。
当前 Phase 1 已实现以下相邻特殊组合：
| 组合 | 效果 |
|---|---|
| 火箭 + 火箭 | 以触发格为中心清除一整行和一整列 |
| 炸弹 + 炸弹 | 以触发格为中心清除半径 2 的方形区域 |
| 彩虹 + 普通宝石 | 清除棋盘上所有同色宝石，并清除参与交换的两个格子 |
| 彩虹 + 彩虹 | 清除整个棋盘上的宝石 |
彩虹 + 火箭、彩虹 + 炸弹、火箭 + 炸弹等更多组合不属于当前 Phase 1 已实现范围。
当前宝石和特殊标记均由 Phaser 代码绘制，便于保持颜色、形状、动效和触控行为一致。后续如需进一步提升材质细节，可将其替换为透明背景的原创、购买授权或明确允许商用的 PNG/WebP 图标；不得从其他游戏截图中裁剪、提取或复刻其图标资源。
- 建议普通宝石提供 6 张、特殊宝石提供 4 张；每张至少
128×128，并保留透明背景。 - 资源建议放在
frontend/public/assets/gems/，也可提供一张精灵图供 Phaser 切分。 - 替换时必须保持现有六色六形映射、四种特殊类型、30 步规则、触控命中区和
prefers-reduced-motion降级逻辑；图标仅替换表现层，不改变规则层。
当前版本不包含登录、注册、账号、云存档、排行榜、数据库、在线同步、多人、AI 对战、广告、内购、分享、成就、每日挑战、固定关卡、障碍物、关卡编辑器或剧情。
- Next.js + React + TypeScript：页面与应用框架。
- Phaser 3：棋盘渲染、输入与动画编排。
- Zustand：轻量 UI 状态。
- Tailwind CSS：样式。
- Vitest：核心规则、渲染辅助和服务测试。
.
├── frontend/ # Next.js 应用、游戏逻辑、测试与前端配置
│ ├── app/ # 页面与全局样式
│ ├── components/ # React HUD 与弹窗
│ ├── i18n/ # 浏览器语言解析与中英文翻译字典
│ ├── game/ # 棋盘、规则、Phaser 场景、动画与输入
│ ├── pwa/ # Service Worker 注册、更新与缓存契约
│ ├── services/ # LocalStorage 与声音服务
│ └── out/ # next build 生成的静态导出产物，不提交
├── docs/ # 面向玩家的中英文指南与视觉参考图
├── proj-info/ # PRD、架构、任务、计划、验证和交接记录
├── AGENTS.md # 开发协作规则
└── README.md # 项目与使用说明
前置条件：安装可用的 Node.js 和 npm。Windows PowerShell 如果受 npm.ps1 执行策略限制，请使用 npm.cmd。
所有命令均从仓库根目录 D:\MyWorks\gem-cascade 执行。
# 安装前端依赖
npm.cmd --prefix frontend install
# 启动开发服务器
npm.cmd run dev开发服务器启动后访问终端显示的本地地址，通常为 http://localhost:3000/。
npm.cmd run lint
npm.cmd run typecheck
npm.cmd run test:run
npm.cmd run build根目录脚本会转发到 frontend/。由于 frontend/next.config.ts 设置了 output: 'export'，成功构建后的静态站点位于 frontend/out/。
- 英文玩法说明：docs/PlayerGuide.md
- 中文玩法说明：docs/PlayerGuide_CN.md
- Phase 1 集成验证记录：proj-info/phase-1-integration-verification.md
当前 Vercel 免费托管的主生产地址为：
https://gem-cascade-wentop.vercel.app/
https://gem-cascade-two.vercel.app/ 也保留为同一项目的备用生产别名。Vercel 每次部署还会生成一个带随机后缀的唯一 deployment URL；该地址只用于定位某一次具体部署、查看构建或回滚，不需要在日常维护中长期保存。
- 顶部的
?图标会打开游戏内 Help。Help 说明玩法、手机/电脑操作、iPhone/iPad 与 Android 的安装步骤，并可用关闭按钮、Escape或“继续游戏”关闭。 - Help 是挂载到页面顶层的可拖动浮窗：桌面端可拖动标题栏移动；短横屏会自动采用三栏紧凑排版。
- 游戏不会提供手动语言选择器。中文浏览器/设备自动显示简体中文，其他语言自动显示英文；修改浏览器语言后刷新页面即可生效。
- Android Chrome：打开稳定生产地址，使用浏览器菜单的“安装应用”或“添加到主屏幕”。
- iPhone Safari：打开稳定生产地址，点“分享”后选择“添加到主屏幕”。
- 发现更新时，游戏会显示“发现新版本”提示；完成当前对局后点“立即刷新”才会切换版本。
- 如需清除本地 PWA 缓存：Chrome/Edge 在 DevTools 的 Application 中注销 Service Worker 并清除站点数据；iPhone 可删除主屏幕图标，再在 Safari 设置中清除该网站数据后重新添加。
- 图标源文件及替换尺寸说明见 proj-info/PWA_ICON_GUIDE.md。
- 也可点击游戏内
?图标查看同一份简化安装指引。
从 GitHub 导入本仓库时使用：
| 配置项 | 值 |
|---|---|
| Root Directory | frontend |
| Install Command | npm install |
| Build Command | npm run build |
| Output Directory | out |
项目不需要在 Vercel 配置环境变量，也不依赖后端服务。当前项目使用 frontend/next.config.ts 中的 output: 'export' 生成静态站点，因此 Vercel 项目应按静态站点部署，输出目录指向 frontend/out/ 对应的 out。
日常重新部署或排查时优先检查主生产别名 https://gem-cascade-wentop.vercel.app/。只有需要对比某一次部署产物、回滚或查看 Vercel 部署详情时，才需要使用具体 deployment URL。
Vercel CLI 手动发布时必须从 frontend/ 目录运行，确保项目的 out 输出目录与 next build 的实际导出位置一致。
开发前请先阅读 AGENTS.md 以及 proj-info/README.md 中列出的控制文档。保持游戏规则与 Phaser 表现层分离；核心规则优先写纯函数和单元测试；不要扩大 Phase 1 范围。