# 关卡版本

在游戏左上角打开选关窗口，通过“关卡版本”切换。首次打开默认使用 v0.5；已保存的版本选择继续保留，不强制迁移。各版本有独立的上次选关位置与通关记录。切换时重新开始目标版本上次选择的关卡，不保存进行到一半的棋盘。

原始版本的设计理念、案例和逐关结构清单见 [v0.1 · 最初 24 关设计理念](v0.1-design-philosophy.md)。本文记录版本管理；两者共同为后续优化提供参照。

| 版本 | 内容 | 关数 | 章节 | 布局来源 |
| --- | --- | ---: | --- | --- |
| v0.1 · 最初设计 | 最初制作的完整关卡，保留名称、顺序、轨道、棋子和原离场额度 | 24 | 3 章 × 8 关 | `ef2724b` 的 `levels/campaign.json` |
| v0.2 · 直线较多版 | 扩展为 48 关时的设计，直线较多 | 48 | 8 章 × 6 关 | `70b021d` 的 `levels/campaign.json` |
| v0.3 · 弯轨观察版 | 弯轨教学与观察版本 | 48 | 8 章 × 6 关 | `levels/campaign-seeds.json`；发布快照归档于 `levels/versions/v0.3.json` |
| v0.4 · 长路与惊喜 | 长路巡游、轻巧反差、清挡与往返换路体验版 | 20 | 4 组 × 5 关 | `levels/v0.4-seeds.json`，生成 `levels/v0.4.json` |
| v0.5 · 千段轨迹 | 六类形态 × 五种体验交替编排 | 1000 | 20 章 × 50 关 | `levels/v0.5-recipes.json`，冻结 `levels/v0.5.json` |

版本号指关卡布局。五版统一使用当前界面、碰撞检测、免费旋转、免费失败试路与撤销规则，包括快速连点与多枚同时离场。旧版文件的 `moveLimit` 原样保留，游戏主界面仍显示待解棋子数。JSON 内的 `version: 1` 是数据格式版本，与 v0.1 等布局版本号无关。

v0.1 的旧闭环与扫掠阻挡也原样保留，可以通过旋转和消除找到解答。24 关与 v0.2 的 48 关均已在当前引擎中求解并完整回放。v0.3 的“每关至少 65% 参考消除路径经过弯道”等发布门槛仅适用于该版，不套用于历史布局。

v0.4 按[新版关卡设计准则](level-design-principles-v2.md)单独制作，全部 20 关同时验证最少旋转参考解和完整体验解。反差关的体验解会直接旋转并启动朝内目标，可能与求解器先清除所有可出棋子的次序不同。逐关关键棋子、路径与验收范围见 [v0.4 体验报告](v0.4-experience-review.md)。

v0.4 选关按钮展示“长路巡游、轻巧反差、清挡放行”等体验类型；旧版继续展示原难度标签。结构分仍保留在分析中，但不将长路线直接等同于高推理难度。

v0.5 选关按章显示，每页 50 关，可直接输入关号；`?campaign=v0.5&level=1000` 可直达第 1000 关。难度采用独立的结构预估，不把长路转弯数加入难度分。每关验证独立最少旋转解、作者解和 20 种策略；六种核心策略与十四种随机探索共同验收，按组记录，均不是玩家概率。[制作报告](v0.5-production-report.md)和[审核页](http://localhost:4173/labs/campaign-review/index.html)记录具体范围。

## 归档与生成

- `levels/versions/v0.1.json`、`v0.2.json`、`v0.3.json` 是对应 Git 文件的原始字节，不重新序列化。
- `levels/versions/provenance.json` 记录来源完整提交、Git blob、SHA-256、字节数、关数与回放结果。
- `npm run levels:versions` 校验归档哈希，生成 `src/levels-archive.js`，供浏览器直接导入。
- `src/campaign-versions.js` 注册版本、章节、关卡模块与旧存档键；`src/levels.js` 保持 v0.3 接口，供原生成器、设计指南与 Cocos 示例使用；`src/levels-v04.js` 暴露 v0.4，浏览器默认选择由版本注册表决定。
- `npm run levels` 重新生成 v0.3，再同步历史模块。`npm run levels:v04` 从新制作卡生成 20 关、双方案回放数据和体验报告。
- `npm run levels:v05` 从确定性制作计划生成 1000 关；`npm run levels:v05:verify` 检查源码指纹、逐关重新求解与完整回放。
- `npm run build` 校验历史归档、生成并验证 v0.4、验证冻结 v0.5，五版均进入静态站点。各版布局来源相互独立。

后续发布新的布局版本时，先将当前主线与出处归档、登记哈希，再在注册表中添加新版本并更新默认版本。为新版本分配新的存档键，不复用旧版完成记录。历史归档保持不变；为历史布局改版应另发版本，不能直接覆盖。

## 进度隔离与迁移

版本选择保存在 `hex-trails-campaign-version`，各版进度保存在 `hex-trails-campaign-v0.1`、`hex-trails-campaign-v0.2`、`hex-trails-campaign-v0.3`、`hex-trails-campaign-v0.4`。旧键仅在对应新键不存在时读取，写入新键，不删除或覆盖旧数据。v0.4 使用新存档槽，不读取旧版完成记录。

| 目标版本 | 对应旧存档键 |
| --- | --- |
| v0.1 | `hex-trails-v2` |
| v0.2 | `hex-trails-observe-v3-r1`（若存在），否则 `hex-trails-observe-v3` |
| v0.3 | `hex-trails-observe-v3-r2` |
| v0.4 | 无，独立新存档 |
| v0.5 | 无，使用 `hex-trails-campaign-v0.5` 独立新存档 |

v0.2 与 v0.3 内部关卡 ID 相同但布局不同，完成记录只按版本隔离，不能按 ID 合并。非法版本回到默认版本，越界关卡索引回到该版第一关，完成列表过滤越界值和重复值。浏览器不允许保存时，当前页面仍可切换并保留各版进度，刷新后无法保留。

自动测试验证历史文件与模块一致、前三版 120 关完整回放、v0.4 双方案回放和替代顺序探索、版本数量与章节、默认选择、跨版本隔离、旧存档迁移与异常存储。Cocos 示例仍通过原接口加载 v0.3；本次未移植 v0.4 到原生工程、实现原生版本选择控件或完成原生实机验证。