《ShelfMatch》柜子三消 · 数值设计文档 v1.0
作者：叶明轩 ｜ 日期：2026-09 ｜ 状态：v1.0（以可玩 Demo 7 关实际实现为准） 配套材料：《ShelfMatch 柜子三消 · 系统设计案 v1.1》、《GoodsMatch 产品拆解案》、可玩 Demo（Godot）
数值来源约定（全文统一）
- [代码:常量名] = 直接取自 Demo 源码（scripts/game_manager.gd 等），与实物一致
- [设计案:R-XX / 章节] = 取自系统设计案 v1.1 原文
- [反推] = 由已实装配置计算得出，非独立设定
- [待定] = 尚未定稿 / 未实测的建议值，明确不冒充已定数值
更新记录 - v1.0（2026-09）：初版，以 7 关实现为准重写数值模型，补全「星级评定 / 结算分」（标注待实装）
1. 数值设计目标
1.1 验证命题
本 Demo 的核心循环是「空间管理 + 时间压力」：在多柜之间挪动物品、凑三同消除、倒计时内清空。数值系统的唯一使命，是让这条循环既撑得起策略深度，又守得住休闲节奏——具体拆成三条可量化目标：
| 目标 | 量化检验标准 |
|---|---|
| 策略可成立 | 每关布局算法保证必有解，玩家失败只能归因"规划慢/错"，不归因"运气差" [反推] |
| 压力可承受 | 单件时间预算随关卡递减，但始终留出"消除续命"的容错空间 [反推] |
| 难度有梯度 | 7 关呈现可感知的递进，且第 1 关可作教学、第 7 关可作满星挑战 [反推] |
1.2 作品集定位
数值文档与系统设计案（第 4 章数值模型）互为补充：本文是落地后、可玩实物对齐的完整数值说明；设计案第 4 章是设计初期的模型推演。两者差异处已逐项注明，作为"设计 → 实现 → 调优"完整证据链的一部分。
2. 五特性分析
按数值模块的五个通用特性，对本作全部数值对象做归类，明确每个数值"从哪来、怎么长、何时亡、如何变、跟谁连"。
| 特性 | 本作对应 | 说明 |
|---|---|---|
| 生成 | 反向生成法产出关卡布局 | 完成态 + K 次合法移动 → 初始布局，保证必可解（见 §8）[代码:reverse_generator.gd] |
| 成长 | 关卡难度递进 | 种类 K、柜子 C、时间 T、打乱步数 K 四变量随关卡单调变化（见 §10）[代码:LEVELS] |
| 消亡 | 三同消除 | 物品生命周期终点：凑齐 3 同 → 消失 + 返还时间 [代码:SCORE_MATCH] |
| 变化 | 倒计时压力 + 道具改局 | 时间单向递减；「打乱」重分配、「加时」回血，不单向成长 [代码:use_prop] |
| 联系 | 数值间的耦合约束 | 分数↔消除、时间↔返还、K↔分散度↔时间预算、道具↔时间上限（见下） |
关键联系（耦合约束）：
- 消除次数 = 物品总数 ÷ 3（每类恒 3 件）→ 单关消除次数被物品数锁定 [反推]
- 消除返还受「初始时间 T」封顶 → 返还不会让时间无限膨胀 [代码:TIME_BONUS + add_time]
- 加时道具与消除返还共用同一上限 → 维持"T = 本关资源总量"的唯一认知 [代码:use_prop]
- 打乱步数 K 决定分散度 → 分散度反哺时间预算的设定 [代码:GENERATOR_K]
3. 核心数值变量定义
| 变量 | 符号 | 取值范围（v1.0） | 对难度的作用方向 |
|---|---|---|---|
| 柜子数量 | C | 4 ~ 10 [代码:LEVELS] |
C↑ → 物品更分散、查找更难（难度↑），但周转空间也↑（难度↓），净效应看配比 |
| 物品种类数 | K | 3 ~ 8 [代码:LEVELS] |
K↑ → 凑对路径变长，难度↑ |
| 每类物品数 | p | 恒 3 [代码:ITEMS_PER_TYPE] |
固定值，保证消除组数 = N/3 为整数 |
| 每柜槽位数 | s | 恒 3 [代码:NUM_SLOTS] |
固定值，决定表层/中层/深层三层结构 |
| 堆叠层数 | L | 恒 3 [反推:槽位数] |
层数固定，规划链深度由"种类 + 柜数"间接决定 |
| 分散度 | D | 由打乱步数 K 控制 [代码:GENERATOR_K] |
D↑ → 同类物品越分散、所需挪动越多，难度↑ |
| 初始时间 | T | 60 ~ 100 秒 [代码:LEVELS] |
T↓ → 压力↑ |
| 打乱步数 | K_shuffle | 10 ~ 100 [代码:GENERATOR_K] |
K_shuffle↑ → 分散度↑，难度↑ |
注意区分「物品种类数 K」与「打乱步数 K_shuffle」两个符号，下文明示避免混淆。
4. 关卡数值总表（7 关）
以下为文档主体，全部数值取自 Demo 实际配置，派生列均 [反推] 计算。
| 关卡 | 柜 C | 种类 K | 每类数 | 物品总数 N | 槽位总数 | 空槽数 | 空柜数 | 初始时间 T(s) | 打乱步数 K_shuffle | 单件时间预算 T/N |
|---|---|---|---|---|---|---|---|---|---|---|
| L1 | 4 | 3 | 3 | 9 | 12 | 3 | 1 | 90 | 10 | 10.0 |
| L2 | 5 | 4 | 3 | 12 | 15 | 3 | 1 | 100 | 20 | 8.3 |
| L3 | 6 | 5 | 3 | 15 | 18 | 3 | 1 | 100 | 35 | 6.7 |
| L4 | 7 | 6 | 3 | 18 | 21 | 3 | 1 | 95 | 50 | 5.3 |
| L5 | 8 | 7 | 3 | 21 | 24 | 3 | 1 | 85 | 65 | 4.0 |
| L6 | 9 | 8 | 3 | 24 | 27 | 3 | 1 | 70 | 85 | 2.9 |
| L7 | 10 | 8 | 3 | 24 | 30 | 6 | 2 | 60 | 100 | 2.5 |
派生列说明 [反推]：
- 物品总数 N = 种类 K × 3
- 槽位总数 = 柜 C × 3；空槽数 = 槽位 − N；空柜数 = 空槽 ÷ 3
- 空柜数 = 柜 C − 种类 K（每种物品在完成态独占 1 柜，见 §8）：L1~L6 恒为 1，L7 为 2
- 单件时间预算 = T ÷ N，保留 1 位小数
5. 时间预算模型
5.1 设计案原公式 [设计案:4.2]
初始时间 T = 基础操作时间 + 物品总数 N × 单件决策时间 s − 分散度修正
（v1.1 初估 s = 3 秒/件）
5.2 实际配置呈现的规律 [反推]
落地后的 7 关时间并非该线性公式的直接取值，而是调优后的一条"单件预算递减"曲线：
| 关卡 | T | N | T/N（单件预算） | 定性 |
|---|---|---|---|---|
| L1 | 90 | 9 | 10.0s | 教学关，预算宽松 |
| L2 | 100 | 12 | 8.3s | 引入堆叠后仍给足余量 |
| L3 | 100 | 15 | 6.7s | 时间持平、物品增多 → 实际更紧 |
| L4 | 95 | 18 | 5.3s | 时间反降，压力抬升 |
| L5 | 85 | 21 | 4.0s | 接近 v1.1 的 3s/件 估算 |
| L6 | 70 | 24 | 2.9s | 触及 s=3s 的下沿 |
| L7 | 60 | 24 | 2.5s | 极限挑战，低于估算线 |
结论（如实说明）：v1.1 的 T = 基础 + N×s 是设计初期的线性估算模型；实际 7 关呈现"单件预算从 10s 递减到 2.5s"的非线性调优结果。两者是"设计模型 vs 调优结果"的关系，不是一一对应，故本文不强行把 7 关数值套回该公式。
5.3 时间规则（已实装）[代码]
| 项目 | 数值 | 来源 |
|---|---|---|
| 初始时间 T | 见 §4 表 | [代码:LEVELS] |
| 消除返还 | +5 秒/次 | [代码:TIME_BONUS] |
| 返还上限 | 封顶 = 本关初始时间 T | [代码:add_time] |
| 警戒阈值 | 剩余 ≤ 10 秒 → 变红提示 | [代码:main.gd:_on_time_updated] |
5.4 消除返还的理论上限 [反推]
单关消除组数 = N ÷ 3，返还理论上限 = (N ÷ 3) × 5s（实际受封顶 T 约束）： L1=15s → L6/L7=40s。返还的价值是"操作好就续命"，而非无限回血。
6. 计分系统
6.1 已实装 [代码]
| 项目 | 数值 | 来源 |
|---|---|---|
| 单次消除得分 | +100 分 | [代码:SCORE_MATCH] |
6.2 已设计 · 待实装 [设计案:4.4 / R-16]
以下两项在设计案中已定义，但当前 Demo 代码尚未实现，故标注「待实装」，不冒充现状。
| 项目 | 定义 | 来源 |
|---|---|---|
| 通关结算分 | 消除分 + 剩余时间 × 10 | [设计案:4.4] |
| 星级评定 | 剩余时间 ≥ 初始时间 40% → ★★★；≥ 15% → ★★；> 0 → ★ | [设计案:R-16] |
6.3 分数定位
v1.0 无外围经济（无货币、无解锁），分数仅用于自我挑战与展示 [设计案:4.4]。
7. 可解性保证（反向生成法）
7.1 原理 [代码:reverse_generator.gd]
从"完成态"（同种类物品归入同一柜）出发，执行 K_shuffle 次遵守游戏规则的合法移动，打乱成开局布局。因每次移动可逆，玩家逆序操作即可还原完成态 → 任意布局必然可解，从算法上消灭死局。
7.2 生成五步流程 [代码:reverse_generator.gd]
- 构造完成态：每种物品独占 1 柜，组内顺序随机
- K_shuffle 次合法移动（禁止即时逆操作，防震荡）
- 定向拆三同：消除开局已成组的柜子
- 随机填充 × 3 轮 + 每轮拆三同，让布局更"乱"
- 反两同：拆掉"同柜 2+ 相同"的柜子（保证前 6 关无两同开局）
7.3 打乱步数 K_shuffle 与分散度
| 关卡 | K_shuffle | 分散度 D（定性） |
|---|---|---|
| L1 | 10 | 低（同类近，易规划） |
| L2 | 20 | 低 |
| L3 | 35 | 中 |
| L4 | 50 | 中 |
| L5 | 65 | 中高 |
| L6 | 85 | 高 |
| L7 | 100 | 极高 |
[代码:GENERATOR_K]。K_shuffle 越大 → 同类越分散 → 所需挪动步数越多 → 难度越高。
7.4 随机性保证 [代码:reverse_generator.gd:generate]
每次重开同一关均调用 randomize() 重新走完整流程，布局不重复（满足"连续重开 10 局布局不同"的验收要求）。
8. 道具数值（已实装）[代码]
| 道具 | 效果 | 每关次数 | 上限 | 来源 |
|---|---|---|---|---|
| 加时 | 倒计时 +10 秒 | 2 次，过关重置 | 封顶 = 初始时间 T | [代码:use_prop] |
| 打乱 | 剩余物品重新随机分配 | 2 次，过关重置 | —（无） | [代码:use_prop + _execute_shuffle] |
设计定位 [设计案:3.8]：反向生成法已保证必可解，「打乱」的定位不是防死局兜底，而是给"思路绕晕"的玩家一次重整理机会；「加时」是限时模式下的压力调节阀。两者共同构成"挫败感保险"，靠次数限制防止依赖。
调参观察点 [设计案:4.6]：
- 打乱使用率显著高于加时 → 关卡布局过绕
- 加时使用率显著高于打乱 → 时间预算偏紧
- 道具使用率 < 20% → 数值感知弱或引导不足
9. 难度曲线分析
9.1 三管齐下的难度递进 [代码:LEVELS]
| 维度 | L1 → L7 | 方向 |
|---|---|---|
| 种类 K | 3 → 8 | 递增（凑对路径变长） |
| 柜数 C | 4 → 10 | 递增（物品更分散） |
| 时间 T | 90 → 60 | 递减（压力增大） |
| 打乱步数 K_shuffle | 10 → 100 | 递增（分散度升高） |
9.2 单件时间预算递减 [反推]
T/N 从 10.0s（L1）一路压到 2.5s（L7），是本作最核心的难度梯度：同样的挪动/消除操作，可用的思考时间逐关收缩，压力从"充裕"过渡到"极限"。
9.3 第 7 关封顶设计 [反推]
物品种类到 8 封顶（物品标签仅 A~H，8 种 [代码:ITEM_LABELS]），第 7 关不再加种类，转而加柜到 10、压时间到 60s、K_shuffle 提到 100继续抬难度，同时空柜数升到 2（周转空间增加作为缓冲），是"硬上限处的综合压力测试"。
9.4 难度锚点（目标通过率）
| 关卡 | 目标通过率 | 来源 |
|---|---|---|
| L1 | ≥ 90% | [设计案:4.3] |
| L2 | ≥ 80% | [设计案:4.3] |
| L3 | ≥ 65% | [设计案:4.3] |
| L4 | ≥ 50% | [设计案:4.3] |
| L5 | 40 ~ 60% | [设计案:4.3] |
| L6 | 建议 30 ~ 50% | [待定]（设计案未覆盖，需实测） |
| L7 | 建议 15 ~ 35%（满星挑战） | [待定]（设计案未覆盖，需实测） |
L6、L7 通过率为建议值，未经过实测，明确标注待定，不冒充既有设计。
10. 调参方法与验证指标
10.1 调参杠杆 [反推]
| 想达到 | 调什么 |
|---|---|
| 某关偏难 | 降 K_shuffle（降分散度）/ 加 T / 减种类 K |
| 某关偏易 | 加 K_shuffle / 减 T / 加种类 K |
| 时间明显不足 | 加 T，或降低种类数（缩短凑对路径） |
| 玩家卡同一点 | 检查该关 K_shuffle 是否过大导致过度分散 |
10.2 埋点事件 [设计案:8.1]
| 事件 | 关键字段 | 用途 |
|---|---|---|
| 关卡开始 | level_id、时间戳 | 尝试次数 |
| 每次移动 | level_id、步序号、耗时 | 决策速度分布 |
| 消除触发 | level_id、剩余时间 | 消除节奏 |
| 胜利 | level_id、剩余时间、总步数 | 通过率、星级分布 |
| 失败 | level_id、剩余物品数、已用步数 | 定位卡点 |
| 道具使用 | level_id、道具类型、剩余时间 | 道具使用率、使用时机 |
10.3 验证指标 [设计案:8.2]
| 指标 | 目标 | 不达标动作 |
|---|---|---|
| L1 首通率 | ≥ 90% | 降 K_shuffle / 加 T |
| L7 通过率 | 待定（建议 15~35%） | 偏离则调 K_shuffle / T |
| 失败时平均剩余物品 | ≤ 30% | > 30% 说明时间预算不足 |
| 平均每步耗时 | 1.5 ~ 3s | > 3s 说明剪影信息不清或布局过绕 |
11. 附录：配置表结构
11.1 关卡配置 level_config [设计案:7.1 + 代码:LEVELS]
| 字段 | 类型 | 示例（L3） |
|---|---|---|
| level_id | int | 3 |
| cabinet_count | int | 6 |
| item_types | int（种类数） | 5 |
| init_time | float | 100 |
| shuffle_steps | int（K_shuffle） | 35 |
11.2 物品配置 item_config [设计案:7.2 + 代码:ITEM_LABELS/ITEM_COLORS]
| 字段 | 说明 |
|---|---|
| item_id | 物品索引 0~7 |
| label | 字母标签 A~H |
| color | 8 色（红/绿/蓝/黄/紫/橙/青/粉） |
设计要点：新增/调整一关 = 改 level_config 一行 + 同步 GENERATOR_K 一项，零代码改动——"配置驱动"思想的落地证明。
本文档数值严格以可玩 Demo 7 关实现为基准，每个数字均标注来源；「待实装」「待定」项已明确区分，不冒充已定/已实现状态。