新增Disciple弟子数据类与DiscipleManager管理器及弟子属性设计文档

2026-09-08 22:49:23 +08:00
parent 18a69f1a17
commit bea9300d2b
6 changed files with 732 additions and 0 deletions
@@ -0,0 +1,124 @@
+# 弟子属性设计
+
+本文件定义弟子（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 的讨论结论整理（本文件前身为占位草稿）