14 KiB
14 KiB
弟子系统设计（D3：生成 + 入宗分流 / D4：名录 UI）
对应开发计划表 D3（8/5）与 D4（8/6）。本文档只描述设计，不包含代码。 状态：D3、D4 已实现
一、数据模型（Disciple）
弟子用一条数据记录表示，不挂在场景树上。
| 字段 | 类型 | 说明 |
|---|---|---|
id |
int | 唯一编号，由 DiscipleManager 自增分配 |
name |
String | 随机生成的姓名 |
age |
int | 入宗年龄（12~18） |
aptitude |
枚举 Aptitude | 资质（入宗分流结果） |
roots |
枚举数组 SpiritRoot | 灵根列表（普通弟子 1~5 根，互不重复） |
is_heavenly |
bool | 天灵根标记（稀有灵根，见枚举二） |
join_year |
int | 入宗年份（0 = 未入宗/候选），accept 时快照 GameState |
join_month |
int | 入宗月份 |
join_day |
int | 入宗日 |
realm_index |
int | 大境界索引（0=练气），D5 修炼系统推进 |
sub_realm_index |
int | 小境界索引（练气层数-1），D5 修炼系统推进 |
枚举一：资质四类（Aptitude）
| 值 | 名称 | 修炼速度倍率 | 说明 |
|---|---|---|---|
| 0 | 下品 | 0.6x | 根基平庸 |
| 1 | 中品 | 1.0x | 资质平平 |
| 2 | 上品 | 1.5x | 天赋尚可 |
| 3 | 天骄 | 2.0x | 万中无一 |
倍率由 D5 修炼循环使用，数值存于 GameConfig（配置
aptitude_speed），此处仅为参考展示。
枚举二：灵根五行（SpiritRoot）
金、木、水、火、土 五种。灵根数量影响灵气容量（容量 = 1 ÷ 根数：单灵根充满、双灵根 1/2、三灵根 1/3……五灵根 1/5，修炼速度按比例折扣），元素种类影响日后生产效率匹配（D6 建筑/职能系统使用），此处只生成不消费。
特殊灵根：天灵根
稀有灵根，独立于五行枚举之外，用 is_heavenly 标记：
| 项目 | 设定 |
|---|---|
| 出现规则 | 仅天骄资质（Aptitude.HEAVENLY）中再掷一次，非天骄弟子不可能有天灵根 |
| 天骄内概率 | 配置 heavenly_root_chance（默认 0.5 = 50%）；总体概率 = 天骄概率 × 天骄内概率（普通难度 5% × 50% ≈ 2.5%） |
| 灵根构成 | 仅一系灵根（五行之一），纯净单灵根 |
| 修炼速度 | 在资质倍率基础上额外 +50%（乘法叠加，数值存于 GameConfig heavenly_bonus，D5 修炼循环消费） |
| 地位 | 宗门争抢的种子弟子，日后可挂靠特殊培养事件（W8 预留） |
天灵根与资质是嵌套关系：先掷资质，天骄之后再判天灵根。天灵根 = 天骄 + 单灵根 + 1.5x 加成，是最稀缺组合。
境界字段说明
新弟子统一为练气一层（realm_index=0, sub_realm_index=0）。境界显示文本规则：
- 练气期：练气 N 层
- 筑基及以上：大境界 + 初/中/后/圆满
境界的成长、突破门槛、寿元计算全部留给 D5 修炼循环，D3 只负责初始状态。
入宗时间字段说明
join_year/month/day在入宗瞬间（accept_applicant）快照 GameState 当前日期- 候选池弟子不设（0），拒绝入宗不产生记录
- 本期只存不消费；入门天数换算（D5 修炼结算）、按入宗排序（列表）、资历事件（W8）后续使用
二、生成规则（随机性）
1. 姓名
- 姓氏池：32 个常用修仙风单姓（林、苏、叶、萧、顾、沈、楚、白……）
- 名用字池：24 个（清、玄、墨、尘、风、澜、霜、珏……）
- 规则：随机 1 个姓 + 1~2 个字（50% 概率双字名）
- 不保证唯一（同名弟子可共存，以 id 区分）
2. 年龄
12~18 岁均匀随机。寿元消耗、大限判断留给 D5。
3. 灵根
- 普通弟子：数量按配置权重随机（
root_count_weights，1~5 根），元素从五行中随机抽取、概率均等、互不重复 - 天灵根：仅天骄资质再判（概率
heavenly_root_chance），灵根数量固定 1 根，修炼速度额外 +50% - 含义：单灵根修炼最快，五灵根最慢（对应修仙世界观）
- 无灵根暂不生成（体修路线预留，见修炼系统设计）
4. 资质（入宗分流）
按权重表掷骰，权重随难度档位变化（配置驱动）：
| 难度 | 下品 | 中品 | 上品 | 天骄 |
|---|---|---|---|---|
| 普通（normal） | 45 | 35 | 15 | 5 |
| 困难（hard） | 60 | 30 | 8 | 2 |
- 当前难度由配置
[recruitment] difficulty指定（"normal"/"hard"） - 权重表在
[recruitment_normal]/[recruitment_hard]节，INI 数组字面量写法：aptitude_weights=[45, 35, 15, 5] - 改配置即调难度，后续可加更多档位（代码字典加一项 + 配置加一节）
三、入宗分流
"入宗分流"的含义：按资质将弟子分为四类，这是生成时的一次性判定，不是持续运行的机制。四类资质弟子日后可能享受不同的培养路线（D4+ 扩展），本期只完成分类本身。
招募机制：定时弹窗招募
招募不是玩家随时点按钮，而是"生成候选 → 暂停时间 → 弹窗选择"：
- 开局招募：新游戏开始，生成 5 名候选，暂停时间弹窗，必须选满 3 名才能确定
- 定期招募：每满间隔（配置文件
recruit_interval_years，当前 0.25 年 = 90 天）生成 3 名候选，暂停时间弹窗 - 选择方式：每个候选独立勾选"入宗"，可全部接受、可全部拒绝（定期招募可 0~3 个）
- 结算：点"确定" → 勾选的入宗、未勾选的拒绝 → 关闭弹窗 → 恢复时间
- 所有参数（候选数、必选数、间隔）来自
resources/game_config.cfg，改配置即改难度
招募流程（文字时序）
- 开局（MainGame 调用
start_new_game()）或倒计时归零（_on_day_passed） - 生成候选弟子（按权重掷资质 → 天骄再判天灵根 → 生成灵根 → 组名字），进入候选池
applicants_generated(is_opening)信号发出 → 弹窗显示候选列表- 玩家勾选（开局模式：确定按钮在选满 3 名前禁用）
- 点"确定" →
finish_recruitment(selected)结算 → 恢复时间 - 控制台打印每位入宗弟子完整信息（姓名/年龄/资质/灵根/境界）—— 本期验收方式
四、DiscipleManager 接口
| 接口 | 签名 | 说明 |
|---|---|---|
start_new_game() |
无 | 清空全部数据 → 开局候选（配置数量）→ 暂停时间 |
generate_applicants(count, is_opening) |
返回无 | 清空候选池 → 生成 count 名候选 → 发信号 |
accept_applicant(d) |
入参候选 | 分配 ID，候选池 → 名录，发信号，控制台打印 |
reject_applicant(d) |
入参候选 | 从候选池移除 |
finish_recruitment(selected) |
入参选中列表 | 结算：selected 内的入宗，其余全部拒绝 |
remove_disciple(d) |
入参弟子 | 移出名录（逐出/陨落） |
reset() |
无 | 清空名录与候选池、ID 与倒计时复位 |
信号 disciples_changed |
无参数 | 名录增删/重置时发出 |
信号 applicants_generated(is_opening) |
bool | 候选生成时发出（弹窗监听） |
内部私有方法（不对外）：生成姓名、生成灵根（含天灵根判定）、掷资质、创建候选、间隔换算。
内部定时机制：
- 字段
_days_until_recruit：距下次定期招募的剩余游戏天数 - 间隔 =
GameConfig.recruit_interval_years× 360 天（TimeSystem 常量换算） - 监听
TimeSystem.day_passed，每日减 1，归零 → 生成候选 →TimeSystem.set_paused(true)（弹窗期间时间冻结）
存放位置：src/Character/（与数据模型同目录），注册为 Autoload 单例，供全局访问。
四·五、配置系统（GameConfig）
所有可调参数集中在 resources/game_config.cfg，由 src/Core/GameConfig.gd（Autoload，声明在 DiscipleManager 之前）启动时读取，缺项回退代码默认值。
[recruitment]
difficulty="normal" ; 当前难度档位
opening_applicant_count=5 ; 开局候选人数
opening_pick_count=3 ; 开局必须选满数
recruit_interval_years=0.25 ; 定期招募间隔（游戏年）
recruit_applicant_count=3 ; 定期弹窗候选人数
heavenly_root_chance=0.5 ; 天灵根概率：仅天骄资质中再掷，50%
root_count_weights=[20, 20, 20, 20, 20] ; 灵根数量权重（1根~5根，和=100 即百分比概率）
[recruitment_normal] ; 普通难度资质权重（下品/中品/上品/天骄）
aptitude_weights=[45, 35, 15, 5]
[recruitment_hard] ; 困难难度资质权重
aptitude_weights=[60, 30, 8, 2]
注意：ConfigFile 用 VariantParser 解析值，数组必须写
[45, 35, 15, 5]字面量，字符串值必须加引号（如difficulty="normal"）；裸写45,35,15,5会被截断为 45 并破坏后续节解析。 以后所有可调参数（天赋权重、价格、境界门槛等）统一加到这里。
五、UI 接入点
- RecruitPanel（
src/UI/Panels/RecruitPanel/）：弹窗场景，挂在 MainGame 下（默认隐藏）- 监听
applicants_generated信号自动弹出 - 每个候选一行：姓名/年龄/资质（天灵根标记）/灵根/境界 + "入宗"勾选框
- 底部：全部接受 / 全部拒绝 / 确定
- 开局模式确定按钮在选满 3 名前禁用；确定后关闭弹窗并恢复时间
- 监听
- 名录的可视化列表见第七节（D4 弟子名录 UI）
六、与后续任务衔接
| 后续任务 | 衔接方式 |
|---|---|
| D4 弟子列表 UI | 监听 disciples_changed 信号 + 遍历 disciples 数组 |
| D5 修炼循环 | 消费 aptitude 倍率与 realm_index/sub_realm_index 字段 |
| D6 建筑/职能系统 | 消费 roots 元素与生产效率匹配 |
| D8 存档接入 | Disciple 数据模型为纯数据，可直接序列化 |
七、弟子名录 UI（D4）
对应开发计划表 D4（8/6）：① 列表条目场景 ② 姓名/资质/境界显示 ③ 点击详情。交付标准：列表可浏览弟子。
1. 入口
- TopBar 顶部栏"管理"按钮（Button_StaffManagement）→ 打开弟子名录面板
- 打开面板时暂停时间（管理操作不打断挂机节奏，避免浏览时弟子入宗/时间流逝；关闭面板恢复推进）
2. 面板结构（两层弹窗，复用青绿仙侠配色）
第一层：名录列表面板（DisciplesPanel）
| 元素 | 说明 |
|---|---|
| 标题 | "弟子名录（N 人）"，N = 当前名录人数 |
| 列表区 | ScrollContainer 动态条目，一个弟子一行，按入宗顺序 |
| 条目内容 | 姓名 / 资质（含天灵根标记）/ 灵根 / 境界 / 修为进度 + "详情"按钮 |
| 空状态 | 名录为空时显示"暂无弟子"提示 |
| 底部 | "关闭"按钮（也可点遮罩关闭） |
第二层：弟子详情弹窗（DiscipleDetailPanel）
| 元素 | 说明 |
|---|---|
| 标题 | 弟子姓名 + 天灵根标记 |
| 信息区 | 静态展示：名字 / 资质 / 年龄 / 灵根 / 境界 / 修为进度 / 入宗时间 |
| 预留区 | 修炼进度、属性面板等 D5+ 扩展位置（本期留白） |
| 底部 | "关闭"按钮 |
3. 数据驱动
- 面板监听
DiscipleManager.disciples_changed→ 重建列表 - 打开面板时也主动刷新一次（保证与名录同步）
- 条目与弟子数据一一对应：动态生成时把 Disciple 引用绑定到条目上，点"详情"直接取用
4. 文件与场景结构
src/UI/Panels/DisciplesPanel/
├── DisciplesPanel.tscn # 名录列表弹窗
├── disciples_panel.gd
├── DiscipleDetailPanel.tscn # 弟子详情弹窗
└── disciple_detail_panel.gd
- 两个弹窗都挂在 MainGame 下（默认隐藏），详情弹窗作为列表面板的子层（显示时盖在列表之上）
- 条目在代码中动态生成（与 RecruitPanel 同套路），不单独做条目场景（D4 拆解的"列表条目场景"用动态行实现即可）
- TopBar"管理"按钮在
top_bar_hud.gd接线，调DisciplesPanel.show_panel()
5. 交互细节
- 详情弹窗从列表面板打开；关闭详情回到列表；关闭列表回到游戏
- 列表浏览期间名录变化（如定期招募入宗）→ 列表实时刷新
- 资质文字可用颜色区分（天骄金色、上品亮青），其余默认——视觉提示，本期可选
八、验收清单（D4 交付标准）
- 点顶部"管理"按钮弹出弟子名录面板，显示当前已入宗弟子
- 列表每行显示：姓名 / 资质（天灵根有标记）/ 灵根 / 境界
- 名录为空时显示"暂无弟子"；招募入宗后列表实时刷新
- 点条目"详情"弹出详情弹窗，显示名字/资质/年龄/灵根/境界/入宗时间
- 关闭详情回到列表，关闭列表回到游戏，无报错
- 打开面板期间时间暂停，关闭面板后时间恢复推进
九、与后续任务衔接（D4 补充）
| 后续任务 | 衔接方式 |
|---|---|
| D5 修炼循环 | 详情弹窗预留区填充：修为进度、突破按钮、寿元 |
| D6 建筑/职能系统 | 列表条目可扩展"职位/职能"列 |
| D8 存档接入 | 名录数据来源不变，仅序列化方式接入 |
十、验收清单（D3 交付标准）
- 项目能正常启动，无脚本报错
- 开局：进入游戏即暂停，弹出"弟子入宗（开局招募）"，显示 5 名候选
- 开局模式确定按钮在选满 3 名前不可用；选满后可确定
- 确定后：勾选的 3 名入宗（控制台打印），时间恢复推进
- 定期：每 90 游戏日（0.25 年 @1x ≈ 45 秒）再次暂停弹窗，显示 3 名候选
- 定期模式可勾选 0~3 名，全部拒绝也可确定；时间正常恢复
- 多次招募后能观察到天灵根弟子（仅天骄中再判 50%，总体概率约 2.5%，弹窗/控制台有标记）
- 修改
game_config.cfg中opening_applicant_count等参数，重启后开局候选数随之变化 - 返回主菜单再进入，名录已清空（reset 生效）