# 弟子属性设计

本文件定义弟子（Disciple）的属性体系、境界规则与派生逻辑，是 `src/Data/Models/Disciple.gd` 的实现依据。关联：`doc/弟子管理.md`（模块设计）、`doc/模块联动.md`（联动规范）、`doc/Roadmap.md`（P1 核心循环）。

## 1. 属性列表（权威定义）

| 名称 | 范围 | 说明 |
|:---|:---|:---|
| metal | [0, 100] | 金属性值 |
| wood | [0, 100] | 木属性值 |
| water | [0, 100] | 水属性值 |
| fire | [0, 100] | 火属性值 |
| earth | [0, 100] | 土属性值 |
| efficiency | [1, 100] | 灵气吸收效率，决定修炼速度，隐藏属性 |
| realm_level | [0, 5] | 大境界，凡人、练气、筑基、金丹、元婴、化神 |
| sub_realm_level | [1, 13] | 凡人只有一个小境界；练气 13 个小境界，其他各有前、中、后、大圆满四个小境界 |
| cultivation_exp | [0, 2147483647] | 修炼经验 |
| farming_exp | [0, 2147483647] | 耕作技能经验 |
| farming_level | [0, 10] | 耕作技能等级 |
| herb_exp | [0, 2147483647] | 药草耕作技能经验 |
| herb_level | [0, 10] | 药草耕作技能等级 |
| alchemy_exp | [0, 2147483647] | 炼丹技能经验 |
| alchemy_level | [0, 10] | 炼丹技能等级 |
| loyalty | [0, 100] | 忠诚度 |

> 字段说明：`id` 只读，由管理器分配；`name` 普通字符串。原设计中的 `is_mortal`、`cultivation_skill`、`alchemy_skill` 单值字段由下述规则取代，不单独存字段。

## 2. 境界体系

大境界 `realm_level` 与显示名、小境界 `sub_realm_level` 数量：

| realm | 名称 | sub 范围 | 小境界显示 |
| --- | --- | --- | --- |
| 0 | 凡人 | 固定 1 | 凡人 |
| 1 | 练气 | 1~13 | 练气X层（1~13 层） |
| 2 | 筑基 | 1~4 | 筑基前期 / 中期 / 后期 / 大圆满 |
| 3 | 金丹 | 1~4 | 金丹前期 / 中期 / 后期 / 大圆满 |
| 4 | 元婴 | 1~4 | 元婴前期 / 中期 / 后期 / 大圆满 |
| 5 | 化神 | 1~4 | 化神前期 / 中期 / 后期 / 大圆满 |

## 3. 灵根（五行推导，不存字段）

有灵根的凡人才能修炼破境。**任一五行属性 ≥ 阈值（占位 20，待调参）即具灵根**：

- 有灵根 → 可修炼：凡人期积累修炼经验，满后破境入练气
- 无灵根 → 终生为凡，永不涨修炼经验（且大境界 0）

派生：`has_spiritual_root()`；凡俗判定 `is_mortal() = (realm_level == 0) 且 无灵根`。

## 4. 经验规则

### 4.1 修炼经验（cultivation_exp）

- 每个小境界有经验上限（曲线表配置，见 §5）
- **跨小境界**：经验满自动突破 sub+1，溢出部分**继承**到下一个小境界
- **跨大境界**：sub 到顶（练气 13 / 其他 4）再满，realm+1 且 sub=1，溢出部分**清零**
- 化神大圆满封顶，不再获得修炼经验
- 突破自动进行（回合结算时处理），暂不设额外条件

### 4.2 技能经验（farming / herb_farming / alchemy 三套相同规则）

- 每跨一级，溢出的经验**继承**到下一级，直到升满（10 级）为止
- 满级后继续获得的经验**不再累积**（经验不会提升）
- 每个等级所需经验由配置文件给出（曲线表，见 §5）

### 4.3 效率的作用

`efficiency` 决定修炼速度（隐藏属性），不直接改变经验上限；具体月收益公式由管理器结算实现，数值待调参。

## 5. 经验曲线表（放 Disciple.gd 内部 const，占位待调参）

> 存储决策：曲线表先以常量写在 `Disciple.gd` 内部，自包含易调；静态内容层方案（CSV/Resource）落地后再迁移。

### 5.1 修炼曲线 CULTIVATION_EXP_CAPS

键为 `"{realm}_{sub}"`，共 30 条（凡人 1 + 练气 13 + 筑基/金丹/元婴/化神 各 4）。凡人期条目（`0_1`）供有灵根凡人积累经验破境用；化神大圆满（`5_4`）无上限（哨兵）。

```
{"0_1": 100, "1_1": 100, "1_2": 110, ... 占位递增，待调参}
```

### 5.2 技能曲线 SKILL_EXP_CAPS

10 条，表示 level N → N+1 所需经验（N = 0~9）。三套技能暂共用一张表，将来可拆分。

```
[100, 120, 140, ...] 占位，待调参
```

## 6. 读写与派生接口（数据类 API）

数值属性读写统一走键名接口（RANGES 为合法键与夹取范围的唯一权威）：

```gdscript
func has_attr(key: String) -> bool      # key 是否为登记表中的数值属性
func get_attr(key: String) -> int       # 读数值属性（未知键 push_error 返回 0）
func set_attr(key: String, value: int) -> bool   # 写数值属性（夹取 + 境界/小境界联动约束）
```

> 说明：`id` 只读语义（由 `create()` 分配），`name` 为字符串不入 RANGES；两者直接字段访问。`total_amount` 为只读属性（实时由五行之和计算）。

派生只读方法（境界体系相关，实现时见 §2）：

| 方法 | 逻辑 |
| --- | --- |
| `total_amount`（只读属性） | 五行之和（实时派生） |
| `has_spiritual_root() -> bool` | 任一五行 ≥ 灵根阈值 |
| `can_cultivate() -> bool` | 有灵根 且 未满级 |
| `is_mortal() -> bool` | realm 0 且无灵根 |
| `sub_realm_max() -> int` | 当前大境界的小境界上限（查 SUB_MAX_BY_REALM） |
| `exp_cap() -> int` | 当前 (realm, sub) 修炼经验上限（查曲线）；满级返哨兵 |
| `realm_name() -> String` | 完整显示名：凡人 / 练气5层 / 筑基后期 / 化神大圆满 |

> 状态迁移（突破、升级、经验增减）属领域操作，归 DiscipleManager（见 `doc/弟子管理.md`），数据类只提供纯查询。

## 7. 夹取与写入约束

- `RANGES` 常量表为 17 个属性的合法范围唯一权威，`create()` 与管理器 `set_attr()` 共用
- 属性全部普通字段（每属性 1 行声明），不带 setter 样板；夹取收口在两处写入口
- 直接写字段不夹取，依赖 `doc/弟子管理.md` "修改只走管理器"纪律

## 8. 变更记录

- 2026-09-07：确立属性列表、境界体系（0~5 + sub）、灵根五行推导、经验曲线表结构；本文档由与 opencode 的讨论结论整理（本文件前身为占位草稿）