Files

T

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

2026-09-08 22:49:23 +08:00

6.0 KiB

Raw Blame History

弟子属性设计

本文件定义弟子（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 为合法键与夹取范围的唯一权威）：

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 的讨论结论整理（本文件前身为占位草稿）

6.0 KiB Raw Blame History Unescape Escape