# 修炼系统设计（D5：修炼循环）

> 对应开发计划表 D5（8/7）：① 修为随时间增长（资质×灵气）② 境界门槛 ③ 突破判定。
> 交付标准：弟子自动修炼，可突破。本文档只描述设计，不包含代码。
> 状态：①②③ 已实现（每日结算 → 修为达门槛升层 → 瓶颈掷骰判定，失败扣 20%；13 层圆满封顶）；修为进度已在管理界面展示

---

## 一、核心循环

```
每日推进 → 修为增长（资质×灵根容量×天灵根×灵气浓度）→ 达到层门槛 → 升层/突破判定 → 境界推进
```

- 纯挂机机制：弟子自动修炼，玩家无需操作
- 修炼只在游戏时间推进时进行（TimeSystem.day_passed），暂停/弹窗期间冻结

---

## 二、修炼速度

**每日修为增量 = 基础速度 × 资质倍率 × 灵根容量倍率 × 天灵根加成 × 灵气浓度**

| 因子 | 来源 | 说明 |
|------|------|------|
| 基础速度 | 配置 `base_speed`（默认 10） | 修为/游戏日 |
| 资质倍率 | 配置 `aptitude_speed`（[0.6, 1.0, 1.5, 2.0]） | 按下品/中品/上品/天骄索引 |
| 灵根容量倍率 | 固定公式 `1 ÷ 根数`（无配置） | 1根=1.0、2根=0.5、3根=1/3、4根=0.25、5根=0.2 |
| 天灵根加成 | 配置 `heavenly_bonus`（1.5） | 仅在 is_heavenly 时乘入 |
| 灵气浓度 | 配置 `qi_concentration`（默认 1.0） | D5 固定值；D6 建筑系统接入后动态化 |

> 所有修炼数值统一从 GameConfig 读取（Disciple 不内置倍率常量），避免双份数值漂移。

### 含义

- **资质定天赋上限**：决定倍率主体（0.6~2.0）
- **灵根数量定灵气容量**：容量 = 1 ÷ 灵根数（硬规则，不提供配置）。单灵根 1 单位灵气即充满（×1.0），双灵根只充 1/2（×0.5），三灵根 1/3，四灵根 1/4，五灵根 1/5，根数越多同一单位灵气分摊越薄
- **天灵根是稀缺加成**：强制单根（满容量）+ 额外 ×1.5，三个维度独立掷骰
- **无灵根（体修路线预留）**：容量为 0，无法练气；暂不生成，待体修系统（炼体）接入后另行结算

组合示例（天骄资质 + 五灵根 = 2.0 × 0.2 = 0.4，慢于 上品资质 + 单灵根 = 1.5 × 1.0 = 1.5）

修为存储用 float（允许小数积累），显示时取整。

---

## 三、境界门槛（本期：练气 1–13 层）

| 层 | 需求修为（配置 `level_thresholds`） | 是否瓶颈 |
|----|----------------------------------|---------|
| 1→2 | 100 | 否 |
| 2→3 | 200 | 否 |
| 3→4 | 350 | **是** |
| 4→5 | 550 | 否 |
| 5→6 | 800 | 否 |
| 6→7 | 1100 | **是** |
| 7→8 | 1500 | 否 |
| 8→9 | 2000 | 否 |
| 9→10 | 2600 | **是** |
| 10→11 | 3300 | 否 |
| 11→12 | 4100 | 否 |
| 12→13 | 5000 | **是** |

- **非瓶颈层**：修为满门槛 → 自动升层（无失败）
- **瓶颈层**（3→4 / 6→7 / 9→10 / 12→13）：修为满后进入突破判定
- 13 层圆满：修为封顶，显示"练气圆满"；筑基以上大境界需丹药/灵石资源，**本期不做**（后续 P2 接入）

> 数值均为示例，正式数值在 D9 平衡调整，只改配置不动代码。

---

## 四、突破判定（瓶颈层）

1. 修为 ≥ 瓶颈层门槛时，每日结算后自动尝试突破
2. 掷骰：成功概率**按瓶颈层分别配置**（`breakthrough_chances`，与 `bottleneck_levels` 一一对应：升 4 层 0.85 / 升 7 层 0.8 / 升 10 层 0.75 / 升 13 层 0.6，越往上越难）
3. **成功** → 升层，控制台打印"X 突破至 练气4层"
4. **失败** → 修为扣减 20%（冲关损耗），次日再尝试；控制台打印失败信息
5. 失败不连续重试（每天最多判定一次）

**设计意图**：挂机友好（全自动），但瓶颈制造节奏感与"卡关→等积累"的经营反馈；损耗惩罚避免无脑挂到顶。

---

## 五、CultivationManager（新 Autoload）

存放位置：`src/Character/CultivationManager.gd`（与 DiscipleManager 同域，注册顺序在 DiscipleManager 之后、声明于 project.godot）

| 接口 | 说明 |
|------|------|
| 监听 `TimeSystem.day_passed` | 每日结算全体弟子 |
| 私有 `_gain_exp(d)` | 按公式累计修为 |
| 私有 `_check_breakthrough(d)` | 门槛判定 + 瓶颈掷骰 |
| 信号 `realm_changed(d)` | 境界变化（详情面板刷新用） |
| 信号 `cultivation_log(text)` | 修炼日志文本（控制台打印/后续日志系统） |

**注意**：只在 `disciples` 名录内结算，候选池不修炼。

---

## 六、配置节（game_config.cfg 新增 [cultivation]）

```ini
[cultivation]
base_speed=10                              ; 基础修为/日
qi_concentration=1.0                       ; 宗门灵气浓度（D6 动态化）
aptitude_speed=[0.6, 1.0, 1.5, 2.0]        ; 资质倍率（下品/中品/上品/天骄）
heavenly_bonus=1.5                         ; 天灵根额外倍率
breakthrough_chances=[0.85, 0.8, 0.75, 0.6]   ; 各瓶颈层突破成功率（与 bottleneck_levels 一一对应）
level_thresholds=[100, 200, 350, 550, 800, 1100, 1500, 2000, 2600, 3300, 4100, 5000]   ; 练气 1→2 到 12→13 各层所需修为
bottleneck_levels=[4, 7, 10, 13]           ; 瓶颈目标层（升到这些层需突破判定）
```

- `aptitude_speed`：与资质枚举一一对应，必须 4 项
- `level_thresholds`：练气 1→2 到 12→13 共 12 个门槛值
- `bottleneck_levels`：升到这些层时需要突破判定

---

## 七、UI 接入（D4 预留区填充）

- **名录列表**（DisciplesPanel）：条目追加"修为"列（如 "1234 / 800"，当前修为/本层门槛；13 层显示"练气圆满"）
- **详情弹窗**：信息区追加"修为：1234 / 2000"（当前/本层门槛；13 层显示 练气圆满）
- 面板打开时暂停时间，进度静态展示；修炼日志：控制台 print（本期不做日志界面）

---

## 八、实现拆解（小步可验证）

1. 配置节 [cultivation] + GameConfig 读取
2. Disciple 加 `cultivation_exp: float` 字段 + 门槛查询辅助
3. CultivationManager 骨架：每日结算修为
4. 非瓶颈自动升层
5. 瓶颈突破判定（成功/失败/损耗）
6. 详情面板修为显示 + realm_changed 刷新
7. 挂机验证（加速时间观察多轮突破）+ 提交

---

## 九、验收清单（D5 交付标准）

- [x] 挂机时弟子修为逐日增长，速度随资质/天灵根不同（下品慢、天骄快）
- [x] 非瓶颈层修为满自动升层，无失败
- [x] 瓶颈层（4/7/10/13 层）需突破判定，控制台有成败日志，失败扣 20% 修为
- [x] 练气 13 层圆满后修为封顶，显示"练气圆满"
- [x] 详情面板显示修为进度，突破后实时刷新
- [x] 修改配置（速度/概率/门槛）重启生效

> 注：修为显示（"当前/本层门槛"）待详情面板接入（拆解第 6 步）。