213 lines
10 KiB
Markdown
213 lines
10 KiB
Markdown
# 建筑系统设计（D6：建筑系统基础）
|
||
|
||
> 对应开发计划表 D6（8/8）：① 灵石矿场景 ② 建造→产出 ③ 升级。交付标准：建筑产资源，升级加速。
|
||
> 本文档只描述设计，不包含代码。
|
||
> 状态：步骤 1–7 已实现（D6 全部完成：食物/开局/配置/建筑模型管理/面板/口粮饥饿离宗），步骤 7 整体挂机验证待 F5 手测
|
||
|
||
---
|
||
|
||
## 一、核心循环
|
||
|
||
```
|
||
建造（花灵石）→ 每日产出（灵石/食物）→ 攒资源升级 → 产出加速 → 支撑修炼/招募经济
|
||
```
|
||
|
||
- 纯挂机产出：与修炼/招募同节奏，监听 `TimeSystem.day_passed` 每日结算
|
||
- 产出直接进入 SectManager 资源（HUD 实时联动）
|
||
|
||
---
|
||
|
||
## 二、数据模型（Building）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `type` | 枚举 BuildingType | 建筑种类（灵石矿 / 灵田） |
|
||
| `level` | int | 等级（1 起） |
|
||
|
||
价格与产出**不在建筑上存副本**，运行时按 `type + level` 从 GameConfig 计算，杜绝数值漂移（与修炼数值同一原则）。
|
||
|
||
### 本期建筑种类
|
||
|
||
| 类型 | 名称 | 产出 | 消费资源 |
|
||
|------|------|------|---------|
|
||
| SPIRIT_STONE_MINE | 灵石矿 | 灵石/日 | 建造/升级花灵石 |
|
||
| SPIRIT_FIELD | 灵田 | 食物/日 | 建造/升级花灵石 |
|
||
|
||
> 食物为通用资源（顶部栏常驻显示，见通用资源分析文档），需在 SectManager 新增。**HUD 显示名为"灵米"**（内部资源名 `food`）。
|
||
>
|
||
> **后续建筑规划**：灵药园（产灵草，修炼资源，W5 炼丹材料）——与灵田分工：灵田管口粮（食物），药园管药材（灵草），加新建筑 = 配置加一节 + 枚举加一项 + 产出分发加一行。
|
||
|
||
> **无地图摆放**：本期建筑统一以面板条目呈现（BuildingsPanel 数据行），灵石矿与灵田同套处理，不建单独场景。地图摆放（建筑实体显示在宗门画面上）属 P2 扩展。
|
||
|
||
---
|
||
|
||
## 三、产出机制
|
||
|
||
- **BuildingManager**（新 Autoload）监听 `day_passed`，遍历已建建筑逐座结算
|
||
- 灵石矿 → `SectManager.add_spirit_stones(output)`
|
||
- 灵田 → `SectManager.add_food(output)`
|
||
- 产出量与等级相关：`产出 = 基础产出 × 升级产出倍率^(等级-1)`
|
||
|
||
## 三·五、口粮消耗与断粮离宗
|
||
|
||
灵田产出的食物有真实用途——**练气期弟子每日吃粮**（筑基+辟谷，为将来预留）。
|
||
|
||
### 断粮后果三方案（选定：方案 B）
|
||
|
||
按修仙设定，练气期尚未辟谷（引气入体 ≠ 断食），仍需进食；通常筑基期逐渐辟谷、金丹期完全辟谷——"断粮有后果"是成立的。具体后果有三档可选：
|
||
|
||
| 方案 | 断粮后果 | 特点 |
|
||
|------|---------|------|
|
||
| **A 饿死** | 断粮累计 N 天（如 30 天）→ 弟子死亡，从名录移除 | 忠于设定，压力最大；但需死亡表现（遗物/坟冢等），范围膨胀 |
|
||
| **B 离宗（选定）** | 断粮累计 N 天 → 弟子出走投奔他处，名录移除 | 效果同 A，叙事更软（"出走"而非"死亡"），UI/代码最简单，契合宗门经营题材 |
|
||
| **C 不致命** | 只修炼效率减半，永远不死 | 最温和，生存压力弱，经济闭环不成立 |
|
||
|
||
**选定理由**：方案 B 的代码量约等于 A（定时检查 + 名录移除，名录/详情 UI 均为现成），但"弟子出走"比"饿死"更符合宗门经营题材的叙事基调，也避开死亡表现系统的范围膨胀，适合 M1 前落地。
|
||
|
||
### 机制细则（方案 B）
|
||
|
||
1. **每日消耗**：`食物 -= 练气弟子数 × 人均消耗`（配置 `consumption_per_disciple`，默认 1）
|
||
2. **断粮判定**：食物不足以覆盖全部练气弟子时 → 食物归 0，全体练气弟子**饥饿天数 +1**；食物充足 → 饥饿天数清零
|
||
3. **饥饿惩罚**：饥饿期间修炼速度 × `hunger_speed_multiplier`（默认 0.5）
|
||
4. **离宗**：饥饿天数 ≥ `hunger_threshold_days`（默认 30）→ 弟子**离宗出走**，从名录移除（控制台日志"X 因断粮离宗"）
|
||
5. 筑基+弟子不消耗口粮（`realm_index != 0` 豁免，为筑基系统预留）
|
||
|
||
**设计意图**：生存压力驱动经济闭环——断粮 → 修炼放缓 → 弟子出走 → 玩家被迫种灵田/合理经营，而不是让食物纯积累无意义。
|
||
|
||
---
|
||
|
||
## 四、建造与升级
|
||
|
||
| 操作 | 规则 |
|
||
|------|------|
|
||
| 建造 | 检查灵石 ≥ 建造价 → 扣除 → 建筑入列（等级 1） |
|
||
| 升级 | 检查灵石 ≥ 升级价 → 扣除 → 等级 +1 |
|
||
| 升级价 | `建造价 × 升级价格倍率^等级`（即升到 2 级花 建造价×倍率） |
|
||
| 等级上限 | 配置 `max_level`（默认 10） |
|
||
|
||
资源不足时：UI 按钮禁用，无其他副作用。
|
||
|
||
---
|
||
|
||
## 五、配置节（game_config.cfg 新增）
|
||
|
||
```ini
|
||
[building] ; 建筑系统通用
|
||
starting_spirit_stones=500 ; 开局灵石（解决初始资金为 0，新游戏发放）
|
||
starting_food=100 ; 开局食物（口粮缓冲，新游戏发放）
|
||
max_level=10 ; 建筑等级上限
|
||
|
||
[building_mine] ; 灵石矿
|
||
cost=200 ; 建造价（灵石）
|
||
output=10 ; 日产出（灵石）
|
||
upgrade_cost_x=2.0 ; 升级价格倍率
|
||
upgrade_output_x=1.5 ; 升级产出倍率
|
||
|
||
[building_field] ; 灵田
|
||
cost=100 ; 建造价（灵石）
|
||
output=5 ; 日产出（食物）
|
||
upgrade_cost_x=2.0 ; 升级价格倍率
|
||
upgrade_output_x=1.5 ; 升级产出倍率
|
||
|
||
[food] ; 口粮与生存
|
||
consumption_per_disciple=1 ; 练气弟子人均日消耗
|
||
hunger_speed_multiplier=0.5 ; 饥饿期间修炼速度倍率
|
||
hunger_threshold_days=30 ; 断粮累计天数上限（达到即离宗）
|
||
```
|
||
|
||
> 加新建筑 = 配置加一节 + 枚举加一项 + BuildingManager 产出分发加一行（对照 `[recruitment_*]` 模式）。
|
||
|
||
---
|
||
|
||
## 六、UI 建筑面板（BuildingsPanel）
|
||
|
||
- **入口**：TopBar"资源"按钮（Button_ResourcesManagement，当前未接线）→ 打开
|
||
- 打开面板时**暂停时间**（与弟子名录面板一致，关闭恢复）
|
||
- 面板结构（复用青绿弹窗模式）：
|
||
- 标题"宗门建筑"
|
||
- 每种建筑一行：名称 / 等级 / 日产出 + 建造或升级按钮（显示价格，资源不足禁用）
|
||
- 底部"关闭"按钮 + 遮罩点击关闭
|
||
- 数据驱动：监听 `buildings_changed` 重建列表，打开时主动刷新
|
||
|
||
---
|
||
|
||
## 七、分步实现规划（小步可验证，每步独立跑通）
|
||
|
||
### 步骤 1：SectManager 加食物资源 + 开局资源发放 ✅
|
||
|
||
| 项 | 内容 |
|
||
|----|------|
|
||
| 改动 | `SectManager.gd` 加 `food` 资源 + `add_food/remove_food` + `food_changed` 信号；`GameConfig.gd` 读 `[building]` 节开局数量；`MainGame.gd` 新游戏时发放 |
|
||
| 验证 | ✅ HUD 显示 500 灵石 / 100 灵米，增减接口调用正确 |
|
||
|
||
### 步骤 2：HUD 食物显示 ✅
|
||
|
||
| 项 | 内容 |
|
||
|----|------|
|
||
| 改动 | `TopBarHUD.tscn` 加"灵米"标签对；`top_bar_hud.gd` 连 `food_changed` 信号 + 初始值 |
|
||
| 验证 | ✅ 开局 100 灵米显示在顶栏；`add_food` 实时刷新 |
|
||
|
||
### 步骤 3：`[building]` 配置节 + GameConfig 读取 ✅（部分）
|
||
|
||
| 项 | 内容 |
|
||
|----|------|
|
||
| 改动 | `game_config.cfg` 加 `[building]`/`[building_mine]`/`[building_field]` 节（开局数量、建筑参数、等级上限）；`GameConfig.gd` 加对应字段 + `building_params` 字典 + 解析 |
|
||
| 验证 | ✅ 无头打印各配置值正确；`[food]` 口粮/饥饿参数待步骤 5 接入 |
|
||
|
||
### 步骤 4：Building 模型 + BuildingManager ✅
|
||
|
||
| 项 | 内容 |
|
||
|----|------|
|
||
| 改动 | `src/Sect/buildings/Building.gd`（type/level + 价格产出计算，运行时读配置）；`src/Sect/BuildingManager.gd`（建造/升级/每日产出/`buildings_changed` 信号）；`project.godot` 注册 Autoload |
|
||
| 验证 | ✅ 建造扣费入列、每日产出进 SectManager、升级后产出提升（10→15）、灵石不足拒绝 |
|
||
|
||
### 步骤 5：口粮消耗 + 饥饿惩罚 + 断粮离宗 ✅
|
||
|
||
| 项 | 内容 |
|
||
|----|------|
|
||
| 改动 | `Disciple.gd` 加 `hunger_days`；`CultivationManager.gd` 每日先结算口粮（消耗→饥饿累计→离宗移除），`_gain_exp` 乘饥饿倍率 |
|
||
| 验证 | ✅ 充足 30 天精确扣减清零；断粮饥饿累计、修为减半；第 30 天离宗（日志"断粮日久，离宗而去"+名录移除）；恢复清零 |
|
||
|
||
### 步骤 6：BuildingsPanel UI + "资源"按钮接线 ✅
|
||
|
||
| 项 | 内容 |
|
||
|----|------|
|
||
| 改动 | `src/UI/Panels/BuildingsPanel/`（面板场景+脚本，每类型一行：名称/等级/日产出+建造或升级按钮）；`TopBarHUD.tscn` 连"资源"按钮 → 新信号 → `MainGame.gd` 打开面板 |
|
||
| 验证 | ✅ 无头验证：打开暂停/关闭恢复、建造升级扣费、每日产出；面板尺寸与名录面板一致（1340×819 vs 1340×842） |
|
||
|
||
### 步骤 7：整体挂机验证 + 提交
|
||
|
||
| 项 | 内容 |
|
||
|----|------|
|
||
| 改动 | 无（仅验证） |
|
||
| 验证 | 挂机模拟：开局 500 灵石→建灵田→产出覆盖口粮→攒灵石升级→产出加速；断粮场景：不建灵田→30 天弟子离宗；对照八节验收清单逐项勾选 |
|
||
|
||
> 依赖关系：1→2 顺序执行（HUD 依赖食物资源）；3→4 顺序执行（Building 依赖配置）；5 依赖 1/3；6 依赖 4；7 为最终验证。
|
||
|
||
---
|
||
|
||
## 八、验收清单（D6 交付标准）
|
||
|
||
- [x] 新游戏开局赠送 500 灵石 + 100 食物（配置可调），HUD 可见
|
||
- [x] 点"资源"按钮打开建筑面板（时间暂停，关闭恢复）
|
||
- [x] 灵石充足时可建造灵石矿/灵田，扣费入列
|
||
- [x] 每日自动产出灵石/食物，HUD 实时增长
|
||
- [x] 升级建筑后产出提升（升级倍率生效），价格按倍率递增
|
||
- [x] 灵石不足时建造/升级按钮禁用
|
||
- [x] 等级达到上限后不可再升级
|
||
- [x] 练气弟子每日消耗食物；断粮后饥饿天数累计、修炼速度减半
|
||
- [x] 断粮累计 30 天弟子离宗（名录移除 + 日志）
|
||
- [x] 食物恢复充足后饥饿清零
|
||
- [x] 建筑/饥饿数据为纯数据（可序列化，D8 存档接入时加 to_dict/from_dict）
|
||
|
||
---
|
||
|
||
## 九、与后续任务衔接
|
||
|
||
| 后续任务 | 衔接方式 |
|
||
|----------|----------|
|
||
| D8 存档接入 | Building 纯数据模型直接序列化 |
|
||
| W3 财政经济 | 建筑产出进入收支流水；俸禄发放扣灵石 |
|
||
| W5 生产制造 | 灵田/灵石矿的弟子匹配度（灵根→效率）接入 |
|
||
| 修炼系统 | 后续灵气建筑（灵泉/聚灵阵）动态化 `qi_concentration` |
|