Files
shanhe-puzzle/README.md
T

121 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 山河拼图
参考用户提供的日本地图下落合并视频开发的小红书离线小工具。正式交付包含**省级版、地级版**;县级素材已备好,未进入游戏发布包。
项目独立存放于 `ProjectRednote/shanhe-puzzle/`。以下命令请在 `shanhe-puzzle` 目录执行。仓库仅跟踪源码、测试和构建脚本、依赖清单、本文档,以及运行和构建校验必需的地图数据。
## 立即预览和打包
```sh
npm ci
npm run dev
# http://localhost:4173
npm test
npm run build
npm run test:browser
npm run test:results
npm run test:interactions
npm run test:container
npm run test:swipes
```
浏览器测试目前默认使用 macOS 已安装的 Google Chrome,路径见 `tests/browser.mjs`。构建要求 Python 3,以及官方 [minitool-zip-builder 1.8.0 Skill](https://fe-static.xhscdn.com/minitool/20261015161653/minitool-zip-builder-1.8.0.skill)。克隆后需将 Skill 解压到本地 `.codex/skills/minitool-zip-builder/`,该目录应直接包含 `SKILL.md`、`references/` 和 `scripts/`。本地工具、依赖、构建输出和报告均已忽略,不推送到代码库。所有运行依赖与地图随最终 ZIP 提供,无联网运行逻辑。
上传产物:`artifacts/shanhe-puzzle-xhs.zip`。根目录直接包含 `index.html`,不是项目源码压缩包。源代码在 `src/`,静态构建在 `dist/`。
**必须在创服平台模拟器、Android 真机扫码、iOS 真机扫码验证同一 ZIP。** 本地浏览器仅用于开发回归和视觉检查,不能替代小红书容器验收。Chrome 61 / Android 8.1 兼容性、CSS 兼容性及真机性能均未实测;原生发笔记、相册授权和保存需要真机验证。
本机预览服务监听 `127.0.0.1:4173`,可以在这台Mac的系统浏览器打开 `http://localhost:4173/`;与Codex内置浏览器使用同一个服务。当前已有服务时无需重复启动。
## 版本范围
- 省级版:全国 34 个省级行政区,各出现一次,合并为一个整体即通关。
- 地级版:选择省或自治区,提供 27 个关卡、333 个地级行政区,包含地级市、自治州、地区、盟。
- 排除县、区、县级市,以及济源、仙桃等省直辖县级单位。数据源会把部分县级单位标为 `city`,构建时进一步用行政区代码排除。
- 北京、天津、上海、重庆、香港、澳门不设地级关卡;数据源暂缺台湾省地级边界,未生成对应地级关卡。
- 本机县级原始边界位于 `data/raw/`,共 335 组、2840 个县级单元;预处理素材位于 `data/county-materials/`,另附独立素材 ZIP。这些开发素材全部保留本地,不进入 Git 或发布包。
## 玩法与得分
进入页选择省级 / 地级版、地区、四档下落速度和三档弹性,点击“开启这局旅程”后开局。在容器内快速轻划并松手,给容器一次惯性晃动;划过位置附近的地块反应更强。每次轻划只在松手时触发一次,地块获得带少量方向、力度差异的冲量后自由运动,手指只能决定大致方向。慢拖、按住、取消触摸或暂停不会持续施力,也不会抓取、牵引或瞬移单块碎片。底部只有一个无文字的圆形暂停图标,统一查看本局旅程、继续、结束或重开;电脑保留方向键辅助。弹跳、倾斜和速度有上限。
只有真实相邻关系、正确地理位置接近时才自动吸合。全部落下后仍可晃动,直到通关、稳定堆过红线超过 2.4 秒,或主动结束。底部圆形暂停图标打开旅程菜单,可继续、结束旅程、重新开局。结束旅程会保留成绩,即使零分或未通关也会生成图片;通关和判负自动生成。
省级海岛使用明确标注的“跨海连接”;地级版中因海域、未纳入本关的省直辖县等产生的间隔,使用明确标注的“隔区连接”。这两种连接都是游戏规则,不能当作陆地邻接关系。入口地图保留相对地理位置。
| 档位 | 出片间隔 | 重力参数 | 得分倍率 |
| --- | ---: | ---: | ---: |
| 佛系看山 | 8.5 秒 | 0.32 | ×1 |
| 说走就走 | 6 秒 | 0.48 | ×1.5 |
| 一路狂飙 | 4 秒 | 0.7 | ×2 |
| 山河起飞 | 2.5 秒 | 1 | ×3 |
每次合并分数 = `(100 + 40 × (合并后块数 − 2)) × 连合系数 × 速度倍率 × 特殊连接系数`,四舍五入到整数。8.5 秒内再次合并视为连合,系数每次增加 0.25,从 1 起、最高 2;跨海和隔区连接额外乘 0.8。通关再奖 `1000 × 速度倍率`。轻划不限次数、不扣分。弹性不改变得分倍率。
弹性三档为“轻轻弹 / 蹦蹦跳 / 弹力全开”,碰撞恢复系数分别为 0.65 / 0.82 / 0.96,同时调整空气阻力、横向冲量和上抛上限。现在最低档对应上一版最高档;默认推荐“蹦蹦跳”,便于腾挪,“弹力全开”需要更好地控制节奏。省级、地级碎片均在上一版基础上线性再缩小 10%;地级仍比相同地图基准额外小 30%;组合过大时仍会全局等比缩放。
最佳纪录按“关卡 + 下落速度 + 弹性”分别保存,旧版纪录对应最低弹性。客户端 9.46.0+ 优先使用官方 Storage;含同步启动信息、异步回退、编译序号剥离及旧纪录迁移。旧环境回退到带异常处理的浏览器存储。
成绩页展示可分享的 750×1400 图片:本局得分、结束时实际容器画面、关卡、速度和弹性、用时、最大拼合 / 最佳连合,以及得分随分钟变化的曲线。曲线从零开始,记录实际得分时刻和结束时间,包含通关奖励,暂停不计时。不会用完整地图冒充未完成的结局。
“发小红书”在玩家点击后调用 `writeTempFile` + `postNote`,携带图片和成绩文案打开图文发布页,玩家可编辑、取消、确认发布;不会自动发布或声称审核成功。“保存成绩图”调用 `writeTempFile` + `saveImageToPhotosAlbum`。无 SDK、接口缺失、授权拒绝、取消或调用失败都有提示,不丢失成绩图;临时路径即用即弃。
当前[官方文档](https://miniapp-sandbox.xiaohongshu.com/minitool/doc#s3-3)支持分享已有视频,但未提供公开录屏 API;屏幕共享被禁用。因此本包不含自动录屏,可用手机系统录屏后自行分享。未使用未公开原生 bridge 或网页屏幕采集。
构建使用已随源码提供的 `src/maps.js`;`research/china.json` 是构建时地图完整性核对必需的源快照。其余 `research/` 文件和整个 `data/` 目录均不入库。下载与预处理脚本仅用于另行更新地图;重生成前需要准备 `research/areas.json` 等原始输入。
## 代码与数据
- `src/core.js`:相邻关系、地理位置与角度吸合判断、计分、纪录清洗。
- `src/game.js`:Matter.js 刚体、出片、组合、胜负、速度、弹性、容器滑动与上晃、得分时间点和尺寸变化。
- `src/app.js`:入口 / 游戏 / 成绩页切换、Canvas 绘制、容器手势与键盘输入、暂停与结束、原生 Storage、发笔记和相册导出。
- `src/result.js`:真实结局快照与得分曲线的成绩图绘制。
- `src/index.html`、`src/style.css`:单入口、响应式布局、安全区和 Chrome 61 样式基线。
- `src/maps.js`:构建期简化的省级 / 地级真实轮廓与预计算连接图。
- `scripts/download-maps.py`、`scripts/download-provinces.py`:仅开发期下载公开地图;后者有台湾省 404 的如实记录。
- `scripts/prepare-maps.py`:简化轮廓、区分行政级别、预计算邻接,输出正式数据和独立县级素材。
- `scripts/check.mjs`、`scripts/build.mjs`、`scripts/package.py`:ES2017 / 离线静态检查、官方 Skill 体积审计、ZIP 结构及完整性验证。
- `tests/`:真实地图可通关性、错误边拒合、朝向一致性、计分、警戒线、整框惯性及入口 / 开局浏览器回归。
地图来源:阿里云 [DataV.GeoAtlas](https://datav.aliyun.com/portal/school/atlas/area_selector),2026-10-16 下载。数据可能落后于最新行政区划,已做游戏用轮廓简化,不能用于导航、测绘或行政区划查询。原始数据提供方条款继续适用,公开可下载不等于获得额外授权。视觉保留岛屿轮廓;物理碰撞对极小区域、退化或相交轮廓采用简化代理。
物理引擎 Matter.js 0.20.0、凹多边形分解 poly-decomp 0.3.0 随包本地提供,许可证见发布包 `licenses.json`。不用 AI、外部 SDK、远程字体、WASM、Worker、网络请求、剪贴板或文件下载能力。
## 检查记录
`artifacts/check-report.json` 是本地语法及资源预检,`artifacts/official-audit.txt` 是官方 Skill 1.8.0 的目录与 ZIP 审计结果,`artifacts/browser-report.json` 是本地浏览器开发回归,`artifacts/package-report.json` 提供包大小和 SHA-256。详细交付检查及待验证项目见 `artifacts/VALIDATION.md`。
## 容器晃动与碎片比例更新
棋盘改为较窄的开口实体容器,侧壁和底边清晰可见,红色警戒线位于顶部 78px。以 320×435 逻辑尺寸为例,全国开局缩放约 0.4995,相对最初约 0.215 的版本仍明显更大,本轮比上一版的0.555再缩小10%。保持各省之间真实比例,微小地区保持真实相对比例,同样通过框体晃动参与拼接。
晃动采用阻尼弹簧模型:容器位移和施加给所有碎片的惯性来自同一状态,并有 14px 的视觉位移限制。在容器内滑动可朝任意方向施加冲量,力度随滑速增加,按与手指的距离平滑衰减;所有组合都受影响,近处更强。移动时只采集手势,在松手时识别一次轻划;使用最近约180ms轨迹,位移至少18px、平均速度至少0.16px/ms,慢拖和按住不触发。触发间隔至少240ms,系统取消或暂停清理尚未触发的手势。键盘左右键仍支持长按。无需加速度计或设备运动 API。
较大组合超出容器可用空间时,全体碎片按相同比例缩小,保持地理相对比例、分数与队列,继续容纳完整地图。难度和拥堵由关卡形状、晃动、速度及弹性共同影响;本地模拟只用于排查物理问题,不能推断真机性能或玩家通关难度。
## 碰撞与晃动手感
碰撞采用160ms轻微压缩回弹、淡轮廓与180ms小接触点,明显弱于合并时的1600ms反馈。渲染形变不修改真实碰撞几何。左右晃动缓存300ms颠起请求,每个物理步在实际接触时处理,避免150ms输入采样错过55ms接触窗口;每组仍有500ms颠起间隔,过期请求不在空中反复加速。暂停/离开页面清理待处理请求。上晃对框内全部组合施加一次向上冲量,420ms 冷却限制快速连点。颠起目标与上抛速度随弹性档位变化,但各档均有上限。最大倾角约 ±9.2°,水平和下落速度也受限,避免无限加速或飞出框。
`tests/shake-preview.mjs` 用真实左右操作和虚拟时钟采集碰撞反馈、速度与截图;`tests/results.mjs` 检查上晃、暂停主动结束、曲线和图片生成、模拟 SDK 参数和失败降级、自然判负及小型关卡真实通关的结算流程。均为本地开发回归,不能替代平台模拟器或真机验收。
`artifacts/bounce-probe.json`记录320×590逻辑尺寸下的实际物理峰值:单块正方形、一次上晃,四种速度分别测得轻弹33~37px、正常97~110px、强弹236~270px。真实地图组合、容器尺寸和接触情况会改变结果。
省级/地级有滑块过渡及水平滑动手势;弹性选项压缩回弹,普通按钮轻按,目的地和弹窗渐入。减少动态效果设置会关闭装饰动画与碰撞形变,保留游戏物理。`npm run test:interactions`覆盖滑动切换、推荐默认档、按钮动画和真实碰撞反馈。
## 手机布局与地图标签修正
顶部在状态栏安全区之外额外预留56px平台操作区。玩法说明移到入口页脚,游戏的旅程设置和暂停/结束移到底部,成绩页返回移入底部操作组;弹窗也避开平台顶部区域。
手机入口保留地图预览,并按设置面板剩余高度分配地图区域;省级展示全国、地级展示所选省区。短屏收紧间距,横屏地图与双栏设置并排,避免地图、面板和页脚互相挤压。
入口和游戏页均按可见视口及安全区排版:在320×568、375×667、390×844以及740×390横屏检查一屏显示;小屏会缩减装饰地图和冗余文案,保留所有主要选择与开局按钮。省区选择采用27项网格,不再使用原生长下拉框,弹窗注明无地级数据的范围。
四档名称为“佛系看山 / 说走就走 / 一路狂飙 / 山河起飞”,速度与倍率参数保持原值。底部仅保留无文字的圆形暂停图标,合并全部旅程操作,容器顶部说明标签已移除,成绩页同样一屏显示。游戏地图先绘制全部形状,再统一绘制标签;名称采用独立布局、边距约束、避让,以及小地区标签底色 / 引线,防止名称贴底被裁或被其他省份覆盖。
构建补回源数据的小离岛外环及独立海域线层,34省级代码、名称及外环数量均与保存的原始数据对比。台湾省14个源外环、香港9个、澳门2个、海南133个全部保留。详见`artifacts/MAP_AUDIT.md`,这不是标准地图审图结论。
`npm run test:container`在现代浏览器模拟平台顶部按钮与四组手机尺寸/安全区,逐页点击并检查布局,不替代小红书真机验证。
`tests/swipes.mjs` 使用真实触摸事件验证单次轻划松手触发、移动中不施力、慢拖和按住过滤、松手后的惯性运动、系统取消、滑动中暂停和恢复、圆形无文字菜单;物理单测另检查附近力度更强、远处仍动、快速更有力和三档边界限制。