HEX TRAILS · 转转六角

一款竖屏六角轨道解谜游戏：点击箭头棋子，让它沿轨道离场；旋转底盘改变路线，在有限步数内清空棋盘。

项目使用原生 JavaScript ES modules 和 Canvas，无第三方运行依赖，无在线字体或 CDN。包含 24 个主线关卡、关卡工坊、求解器、确定性关卡生成器，以及 Cocos Creator 适配示例。

快速开始

需要 Node.js 20 或更高版本，以及 Git；无需执行 npm install。

git clone git@git.zeroplus.fun:Zeroplus/HexTrails.git
cd HexTrails
npm run dev

打开游戏。请通过 HTTP 访问，直接双击 HTML 文件无法正常加载 ES modules。开发服务监听 0.0.0.0，同一局域网的手机可通过电脑 IP 和端口访问。

关卡工坊：当前精简游戏界面隐藏工坊导航，通过此地址进入。
交互设计规范：色板、图标、组件状态与动效示例。
修改端口：PORT=4174 npm run dev。

游戏规则

点击棋子，从箭头方向进入轨道；弯道自动转向，交叉处不换轨。
点击左右旋转按钮，或沿棋盘边缘拖动，将底盘旋转 60°。棋子的位置与箭头方向保持不动，底板格子与轨道配对一起旋转。
棋子不能穿过其他棋子。碰撞检测覆盖整段运动路径，包括弯道与邻格擦碰；碰撞动画展示接触后退回原位。
点击棋子或旋转底盘各消耗 1 步，碰撞也扣步。撤销恢复棋盘、棋子、朝向和步数；没有倒计时。
提示会高亮可安全离场的棋子，或建议旋转方向。棋子配色不影响规则。

主线关卡均经过求解验证，且需要旋转才能完成。所有关卡可自由选择，通关进度保存在当前浏览器。音效使用 Web Audio 合成，首次交互后启用，可在设置中关闭并保存偏好。

关卡工坊

工坊支持 19 格和 37 格底板、棋子方向与配色、15 种轨道配对、单格轨道旋转和整体底盘旋转；还提供擦除、路径检查、撤销编辑、试玩、随机生成、本机单槽存档及 JSON 导入导出。

试玩不修改草稿，也不计入主线进度。工坊与正式游戏共用碰撞及求解规则，显示可解性、必要旋转数、最短步数与结构难度评分。搜索达到上限时显示“尚未确定”，不直接判定无解。

不具备六重旋转对称性的导入底板会禁用整体旋转。导入失败保留当前草稿；不可解关卡仍可保存用于调试。浏览器存档不会跨设备同步，需长期保存或分享时请导出 JSON。

关卡字段、导入限制、求解算法和评分公式见关卡设计说明。

开发与构建

命令	用途
`npm run dev`	启动本地开发服务，默认端口 4173
`npm test`	执行 Node 内置测试套件
`npm run build`	生成设计资源并输出静态站点到 `dist/`
`npm run levels`	使用固定种子重新生成关卡，同步两个关卡数据文件
`npm run design`	生成颜色 token、CSS、JSON、PNG、对比度报告和设计指南 HTML
`node scripts/serve.mjs --dist`	本地预览构建产物

部署时先执行 npm run build，再将 dist/ 的内容上传至静态网站服务器。站点无需后端服务。构建会清空并重建 dist/；不要提交 dist/ 或 node_modules/。

修改语义颜色时编辑 src/design-tokens.js，然后运行 npm run design 并检查生成资源的差异。修改关卡生成逻辑后运行 npm run levels 和 npm test，确保关卡数据同步且全部可解。

项目结构

路径	职责
`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 适配示例
`wechat/HexTrail/`	Cocos Creator 3.8.8 工程，后续游戏移植的目标工程
`docs/`	玩法分析、关卡设计和移植说明

规则与数学模块不依赖 DOM、存储 API 或浏览器物理引擎。新增玩法应留在模型层，浏览器输入与存储逻辑留在适配层。

美术与移植

当前界面采用蓝灰背景、暖白棋盘、哑光棋子和生成图标。主要资源为 assets/tiles-matte-clean-v8.png、assets/ui-icons-generated.png 和 assets/ui-surfaces.png；裁切与颜色定义以源码为准，历史素材不一定用于当前界面。

Design.md 记录设计规范；Design.html 内嵌图片与样式，可单文件离线分享。生成过程与提示词见素材说明。

Cocos 示例复用规则、碰撞、渲染命令和图集；HTML 控件、文件导入导出与存储需替换成宿主接口。接入步骤见 Cocos 移植指南。wechat/HexTrail/ 是本仓库管理的 Cocos Creator 3.8.8 工程，后续将把当前游戏移植到该工程中。使用 Creator 打开该目录；工程自身的 .gitignore 排除缓存、本地配置和构建产物，源码与项目配置随主仓库提交。

验证与已知限制

自动测试覆盖主线完整解答、生成关卡、旋转与撤销、弯轨寻路、连续碰撞、闭环、导入校验，以及设计颜色对比度和图标裁切。测试结果以当前 npm test 输出为准。

界面变更还需在浏览器检查竖屏布局、旋转、碰撞回位、弹窗和工坊导入导出；自动测试不替代实机交互验收。较小屏幕可能需要纵向滚动。难度评分是结构估计，尚未通过玩家数据标定。

cocos/ 是适配示例，不是完整 Creator 工程；原生场景及 Android/iOS 构建尚未完成验收。docs/ui-layout.json 是旧版布局快照，不应直接作为当前场景模板。

更多背景见视频与规则分析。

6.6 KiB Raw Permalink Blame History