npm run dev          # http://localhost:4173
npm test             # 规则、旋转、连续碰撞及关卡验证
npm run build        # 静态网站输出到 dist/
npm run levels       # 固定种子重新生成 24 关
npm run design       # 从颜色 token 输出 CSS、JSON、PNG 与对比度报告

也可用 node scripts/serve.mjs --dist 预览构建产物。默认端口 4173，可用 PORT=4174 npm run dev 修改。请通过 HTTP 打开；同一局域网手机可以访问电脑 IP 和端口。

游戏规则

点击棋子，从箭头方向进入轨道；弯道自动转向，交叉处不换轨。
左右按钮或沿棋盘边缘拖动，将整块轨道底盘旋转 60°。棋子位置与箭头保持不动，底盘的格子位置与轨道配对一起旋转，实际路线改变。
棋子具有六边形占用范围。检测整段运动路径，包括弯道和擦碰；不能穿过其他棋子。碰撞时走到接触处，再退回原位。
点击或转盘各消耗 1 步，碰撞也扣步；撤销恢复棋盘、棋子、朝向和步数。没有倒计时。
提示会建议安全棋子，或高亮应该使用的旋转方向。

24 个关卡均按旋转与碰撞规则验证可解，且都至少需要一次旋转；难度 25–75，必要旋转 1–3 次。所有关卡可自由选择，通关进度保存在本机浏览器。配色不影响规则。

美术与界面

当前采用纯色蓝灰背景、暖白棋盘、明快哑光棋子与生成的扁平图标。界面采用单屏 HUD、大旋转箭头和底部工具栏；关卡地图、规则和难度放在弹窗里。配色、组件、素材和验收标准见 Design.md，颜色数值统一维护在 src/design-tokens.js。

设计师可直接打开 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 导入导出。试玩不修改草稿、不计主线进度。

评分、生成器与游戏使用同一套碰撞规则，实时显示可解性、必要旋转和最短步数。不规则导入底板可以游玩，但如果不具备六重旋转对称性，会禁用整体旋转。导入失败保留现有草稿；不可解关卡仍可保存用于调试。

文件结构

文件	作用
`src/core.js`	规则、转盘、求解器、生成器、评分、验证
`src/path-math.js`	渲染与碰撞共享的曲线采样、连续扫掠计算
`src/geometry.js`	屏幕布局、命中检测与路径插值
`src/renderer.js`	引擎无关场景绘制及 Canvas 适配
`src/sprites.js`	图集源矩形与顶面锚点
`src/app.js`	浏览器 UI、输入、动画和存档
`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 控件在原生端需换成宿主接口。

验证范围

27 项自动测试通过，覆盖 24 关完整动作序列、100 个生成种子、旋转解锁、转盘撤销、弯轨寻路、邻格擦碰、连续扫掠防穿透、闭环、导入校验、16 组语义颜色对比度与生成图标裁切。浏览器验证了新图集、390×844 布局、碰撞回位和旋转扣步。Cocos 示例通过 TypeScript 语法检查，尚未在 Creator 场景或原生构建中运行验收。

视频与规则说明 · 难度与关卡数据 · Cocos 接入 · 素材与提示词

图片 UI 资源

图标和棋子使用生成的 PNG 图集，按钮与弹窗使用 token 输出的纯色 PNG。网页通过 CSS 管理布局、圆角和状态；Cocos 使用 Sprite 与圆角 Mask。动态文字继续使用 Label，方便中文显示和本地化。

assets/tiles-matte-clean-v8.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 语法检查，尚未在完整原生场景中逐像素验收。

当前背景为无花纹的蓝灰色 #A8BECF，工具统一蓝灰底色，主操作统一紫色。棋子采用明快哑光色与小圆角，黄色棋子的箭头使用深色以提高可读性。碰撞动画分为接近、接触停顿、被挡棋子震动和弹回，逻辑位置不变。

精简游戏界面只显示 Level、剩余步数、棋盘和操作区。关卡工坊仍可通过 ?editor=1 访问，不占用游戏底部导航。

扁平控件、弹窗和音效

全套图标使用 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 和长按菜单。

README.md Unescape Escape

HEX TRAILS · 转转六角

运行与构建