docs: refresh project README and development guide
This commit is contained in:
cabinw
@@ -1,88 +1,95 @@
|
|||||||
# HEX TRAILS · 转转六角
|
# HEX TRAILS · 转转六角
|
||||||
|
|
||||||
竖屏休闲解谜游戏：让箭头棋子沿弯曲轨道离场，旋转底盘改变路线，避开沿途其他棋子。
|
一款竖屏六角轨道解谜游戏：点击箭头棋子，让它沿轨道离场；旋转底盘改变路线，在有限步数内清空棋盘。
|
||||||
|
|
||||||
## 运行与构建
|
项目使用原生 JavaScript ES modules 和 Canvas，无第三方运行依赖，无在线字体或 CDN。包含 24 个主线关卡、关卡工坊、求解器、确定性关卡生成器，以及 Cocos Creator 适配示例。
|
||||||
|
|
||||||
Node.js 20+，无第三方运行依赖，无在线字体或 CDN。
|
## 快速开始
|
||||||
|
|
||||||
|
需要 Node.js 20 或更高版本，以及 Git；无需执行 `npm install`。
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm run dev # http://localhost:4173
|
git clone git@git.zeroplus.fun:Zeroplus/HexTrails.git
|
||||||
npm test # 规则、旋转、连续碰撞及关卡验证
|
cd HexTrails
|
||||||
npm run build # 静态网站输出到 dist/
|
npm run dev
|
||||||
npm run levels # 固定种子重新生成 24 关
|
|
||||||
npm run design # 从颜色 token 输出 CSS、JSON、PNG 与对比度报告
|
|
||||||
```
|
```
|
||||||
|
|
||||||
也可用 `node scripts/serve.mjs --dist` 预览构建产物。默认端口 4173，可用 `PORT=4174 npm run dev` 修改。请通过 HTTP 打开；同一局域网手机可以访问电脑 IP 和端口。
|
打开 [游戏](http://localhost:4173/)。请通过 HTTP 访问，直接双击 HTML 文件无法正常加载 ES modules。开发服务监听 `0.0.0.0`，同一局域网的手机可通过电脑 IP 和端口访问。
|
||||||
|
|
||||||
|
- [关卡工坊](http://localhost:4173/?editor=1)：当前精简游戏界面隐藏工坊导航，通过此地址进入。
|
||||||
|
- [交互设计规范](http://localhost:4173/Design.html)：色板、图标、组件状态与动效示例。
|
||||||
|
- 修改端口：`PORT=4174 npm run dev`。
|
||||||
|
|
||||||
## 游戏规则
|
## 游戏规则
|
||||||
|
|
||||||
- 点击棋子，从箭头方向进入轨道；弯道自动转向，交叉处不换轨。
|
- 点击棋子，从箭头方向进入轨道；弯道自动转向，交叉处不换轨。
|
||||||
- 左右按钮或沿棋盘边缘拖动，将整块轨道底盘旋转 60°。**棋子位置与箭头保持不动**，底盘的格子位置与轨道配对一起旋转，实际路线改变。
|
- 点击左右旋转按钮，或沿棋盘边缘拖动，将底盘旋转 60°。棋子的位置与箭头方向保持不动，底板格子与轨道配对一起旋转。
|
||||||
- 棋子具有六边形占用范围。检测整段运动路径，包括弯道和擦碰；不能穿过其他棋子。碰撞时走到接触处，再退回原位。
|
- 棋子不能穿过其他棋子。碰撞检测覆盖整段运动路径，包括弯道与邻格擦碰；碰撞动画展示接触后退回原位。
|
||||||
- 点击或转盘各消耗 1 步，碰撞也扣步；撤销恢复棋盘、棋子、朝向和步数。没有倒计时。
|
- 点击棋子或旋转底盘各消耗 1 步，碰撞也扣步。撤销恢复棋盘、棋子、朝向和步数；没有倒计时。
|
||||||
- 提示会建议安全棋子，或高亮应该使用的旋转方向。
|
- 提示会高亮可安全离场的棋子，或建议旋转方向。棋子配色不影响规则。
|
||||||
|
|
||||||
24 个关卡均按旋转与碰撞规则验证可解，且都至少需要一次旋转；难度 25–75，必要旋转 1–3 次。所有关卡可自由选择，通关进度保存在本机浏览器。配色不影响规则。
|
主线关卡均经过求解验证，且需要旋转才能完成。所有关卡可自由选择，通关进度保存在当前浏览器。音效使用 Web Audio 合成，首次交互后启用，可在设置中关闭并保存偏好。
|
||||||
|
|
||||||
## 美术与界面
|
|
||||||
|
|
||||||
当前采用纯色蓝灰背景、暖白棋盘、明快哑光棋子与生成的扁平图标。界面采用单屏 HUD、大旋转箭头和底部工具栏；关卡地图、规则和难度放在弹窗里。配色、组件、素材和验收标准见 [Design.md](Design.md)，颜色数值统一维护在 `src/design-tokens.js`。
|
|
||||||
|
|
||||||
设计师可直接打开 [Design.html](Design.html)：包含可复制的色板、对比度表、实际图标与棋子、按钮状态、弹窗动效和完整规范。图片与样式已内嵌，分享这一个文件即可离线查看。开发服务中的访问地址为 `http://localhost:4173/Design.html`，同一局域网可使用电脑 IP 替换 localhost。修改 Design.md 或 token 后运行 `npm run design` 同步 HTML；`npm run build` 也会自动生成并复制到 dist。
|
|
||||||
|
|
||||||
390×844 下主要游戏内容完整显示。较小屏幕优先保留棋子可点击尺寸，必要时允许纵向滚动。
|
|
||||||
|
|
||||||
## 关卡工坊
|
## 关卡工坊
|
||||||
|
|
||||||
可编辑 19/37 格底板、棋子方向和配色、15 种轨道配对、单格轨道旋转及整块底盘旋转。支持擦除、路径检查、撤销编辑、试玩、随机生成、本机单槽存档、JSON 导入导出。试玩不修改草稿、不计主线进度。
|
工坊支持 19 格和 37 格底板、棋子方向与配色、15 种轨道配对、单格轨道旋转和整体底盘旋转；还提供擦除、路径检查、撤销编辑、试玩、随机生成、本机单槽存档及 JSON 导入导出。
|
||||||
|
|
||||||
评分、生成器与游戏使用同一套碰撞规则，实时显示可解性、必要旋转和最短步数。不规则导入底板可以游玩，但如果不具备六重旋转对称性，会禁用整体旋转。导入失败保留现有草稿；不可解关卡仍可保存用于调试。
|
试玩不修改草稿，也不计入主线进度。工坊与正式游戏共用碰撞及求解规则，显示可解性、必要旋转数、最短步数与结构难度评分。搜索达到上限时显示“尚未确定”，不直接判定无解。
|
||||||
|
|
||||||
## 文件结构
|
不具备六重旋转对称性的导入底板会禁用整体旋转。导入失败保留当前草稿；不可解关卡仍可保存用于调试。浏览器存档不会跨设备同步，需长期保存或分享时请导出 JSON。
|
||||||
|
|
||||||
| 文件 | 作用 |
|
关卡字段、导入限制、求解算法和评分公式见 [关卡设计说明](docs/level-design.md)。
|
||||||
|
|
||||||
|
## 开发与构建
|
||||||
|
|
||||||
|
| 命令 | 用途 |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
| `src/core.js` | 规则、转盘、求解器、生成器、评分、验证 |
|
| `npm run dev` | 启动本地开发服务，默认端口 4173 |
|
||||||
| `src/path-math.js` | 渲染与碰撞共享的曲线采样、连续扫掠计算 |
|
| `npm test` | 执行 Node 内置测试套件 |
|
||||||
| `src/geometry.js` | 屏幕布局、命中检测与路径插值 |
|
| `npm run build` | 生成设计资源并输出静态站点到 `dist/` |
|
||||||
| `src/renderer.js` | 引擎无关场景绘制及 Canvas 适配 |
|
| `npm run levels` | 使用固定种子重新生成关卡，同步两个关卡数据文件 |
|
||||||
| `src/sprites.js` | 图集源矩形与顶面锚点 |
|
| `npm run design` | 生成颜色 token、CSS、JSON、PNG、对比度报告和设计指南 HTML |
|
||||||
| `src/app.js` | 浏览器 UI、输入、动画和存档 |
|
| `node scripts/serve.mjs --dist` | 本地预览构建产物 |
|
||||||
| `Design.md`、`src/design-tokens.js` | 设计规范与语义颜色的唯一数值来源 |
|
|
||||||
| `design/` | 生成的 token、对比度报告与组件样式绑定 |
|
|
||||||
| `assets/` | 实际游戏 PNG 素材及生成提示词 |
|
|
||||||
| `levels/campaign.json` | 24 关数据；生成脚本同步 `src/levels.js` |
|
|
||||||
| `cocos/HexTrailsBoard.ts` | Graphics + Sprite 图集适配示例 |
|
|
||||||
|
|
||||||
规则和数学层不依赖 DOM，碰撞不依赖浏览器物理引擎。Cocos 示例复用相同图集、碰撞、旋转与提示模型。浏览器文件选择/下载、本地存储及 HTML 控件在原生端需换成宿主接口。
|
部署时先执行 `npm run build`，再将 `dist/` 的内容上传至静态网站服务器。站点无需后端服务。构建会清空并重建 `dist/`；不要提交 `dist/` 或 `node_modules/`。
|
||||||
|
|
||||||
## 验证范围
|
修改语义颜色时编辑 `src/design-tokens.js`，然后运行 `npm run design` 并检查生成资源的差异。修改关卡生成逻辑后运行 `npm run levels` 和 `npm test`，确保关卡数据同步且全部可解。
|
||||||
|
|
||||||
27 项自动测试通过，覆盖 24 关完整动作序列、100 个生成种子、旋转解锁、转盘撤销、弯轨寻路、邻格擦碰、连续扫掠防穿透、闭环、导入校验、16 组语义颜色对比度与生成图标裁切。浏览器验证了新图集、390×844 布局、碰撞回位和旋转扣步。Cocos 示例通过 TypeScript 语法检查，尚未在 Creator 场景或原生构建中运行验收。
|
## 项目结构
|
||||||
|
|
||||||
[视频与规则说明](docs/video-analysis.md) · [难度与关卡数据](docs/level-design.md) · [Cocos 接入](docs/cocos-port.md) · [素材与提示词](assets/GENERATION.md)
|
| 路径 | 职责 |
|
||||||
|
| --- | --- |
|
||||||
|
| `index.html`、`style.css` | 响应式浏览器界面 |
|
||||||
|
| `src/core.js` | 游戏规则、旋转、求解、生成、评分与导入校验 |
|
||||||
|
| `src/path-math.js` | 渲染与连续碰撞共享的路径数学 |
|
||||||
|
| `src/geometry.js`、`src/tile-shape.js` | 坐标转换、命中检测与棋子轮廓 |
|
||||||
|
| `src/renderer.js` | 引擎无关绘制命令与 Canvas 适配 |
|
||||||
|
| `src/app.js`、`src/ui.js`、`src/audio.js` | 浏览器交互、界面、存档与音效 |
|
||||||
|
| `src/collision-animation.js` | 碰撞反馈动画 |
|
||||||
|
| `src/sprites.js`、`src/ui-skin.js` | 棋子与 UI 图集裁切、共享皮肤定义 |
|
||||||
|
| `src/design-tokens.js`、`design/` | 语义颜色源与生成的设计资源 |
|
||||||
|
| `levels/campaign.json`、`src/levels.js` | 主线关卡 JSON 与浏览器模块 |
|
||||||
|
| `assets/` | PNG 图集、历史素材与生成提示词 |
|
||||||
|
| `tests/`、`scripts/` | 自动测试、开发服务和生成脚本 |
|
||||||
|
| `cocos/` | Cocos Creator 棋盘及 UI 适配示例 |
|
||||||
|
| `docs/` | 玩法分析、关卡设计和移植说明 |
|
||||||
|
|
||||||
### 图片 UI 资源
|
规则与数学模块不依赖 DOM、存储 API 或浏览器物理引擎。新增玩法应留在模型层，浏览器输入与存储逻辑留在适配层。
|
||||||
|
|
||||||
图标和棋子使用生成的 PNG 图集，按钮与弹窗使用 token 输出的纯色 PNG。网页通过 CSS 管理布局、圆角和状态；Cocos 使用 Sprite 与圆角 Mask。动态文字继续使用 Label，方便中文显示和本地化。
|
## 美术与移植
|
||||||
|
|
||||||
- `assets/tiles-matte-clean-v8.png`：新版平滑糖果棋子。
|
当前界面采用蓝灰背景、暖白棋盘、哑光棋子和生成图标。主要资源为 `assets/tiles-matte-clean-v8.png`、`assets/ui-icons-generated.png` 和 `assets/ui-surfaces.png`；裁切与颜色定义以源码为准，历史素材不一定用于当前界面。
|
||||||
- `assets/ui-surfaces.png`：13 个由颜色 token 输出的纯色色块。
|
|
||||||
- `assets/ui-icons-generated.png`：用户选定的十六种生成图标，保留原图造型。
|
|
||||||
- `src/ui-skin.js`：两端共用的面板与图标裁切参数。
|
|
||||||
- `cocos/CandyUiSkin.ts`：Cocos SpriteFrame 与圆角 Mask 适配组件。
|
|
||||||
- `docs/ui-layout.json`：390×844 主界面位置参考。
|
|
||||||
|
|
||||||
Cocos 组件经过 TypeScript 语法检查，尚未在完整原生场景中逐像素验收。
|
[Design.md](Design.md) 记录设计规范；[Design.html](Design.html) 内嵌图片与样式，可单文件离线分享。生成过程与提示词见 [素材说明](assets/GENERATION.md)。
|
||||||
|
|
||||||
当前背景为无花纹的蓝灰色 `#A8BECF`，工具统一蓝灰底色，主操作统一紫色。棋子采用明快哑光色与小圆角，黄色棋子的箭头使用深色以提高可读性。碰撞动画分为接近、接触停顿、被挡棋子震动和弹回，逻辑位置不变。
|
Cocos 示例复用规则、碰撞、渲染命令和图集；HTML 控件、文件导入导出与存储需替换成宿主接口。接入步骤见 [Cocos 移植指南](docs/cocos-port.md)。`wechat/HexTrail/` 属于独立 Cocos 工程仓库，已从本仓库忽略。
|
||||||
|
|
||||||
精简游戏界面只显示 Level、剩余步数、棋盘和操作区。关卡工坊仍可通过 `?editor=1` 访问，不占用游戏底部导航。
|
## 验证与已知限制
|
||||||
|
|
||||||
### 扁平控件、弹窗和音效
|
自动测试覆盖主线完整解答、生成关卡、旋转与撤销、弯轨寻路、连续碰撞、闭环、导入校验，以及设计颜色对比度和图标裁切。测试结果以当前 `npm test` 输出为准。
|
||||||
|
|
||||||
全套图标使用 `assets/ui-icons-generated.png`，按实际图形边界裁成正方形并居中，等比显示。旧的代码重绘版 `ui-icons-flat.png` 已退出当前界面。按钮和弹窗使用语义色面板。通关/失败结果为原生 modal dialog，背景遮罩及模糊，拦截底层触摸；星星按 0.30/0.49/0.68 秒依次出现。支持系统减少动态效果设置。
|
界面变更还需在浏览器检查竖屏布局、旋转、碰撞回位、弹窗和工坊导入导出；自动测试不替代实机交互验收。较小屏幕可能需要纵向滚动。难度评分是结构估计，尚未通过玩家数据标定。
|
||||||
|
|
||||||
`src/audio.js` 用 Web Audio 合成轻量点击、离场、旋转、碰撞与结果音效，首次触摸后启用，可在设置里关闭并记住偏好。手机棋盘关闭 WebKit tap highlight 和长按菜单。
|
`cocos/` 是适配示例，不是完整 Creator 工程；原生场景及 Android/iOS 构建尚未完成验收。`docs/ui-layout.json` 是旧版布局快照，不应直接作为当前场景模板。
|
||||||
|
|
||||||
|
更多背景见 [视频与规则分析](docs/video-analysis.md)。
|
||||||
|
|||||||
Reference in New Issue
Block a user