# 建筑系统设计（D6：建筑系统基础）

> 对应开发计划表 D6（8/8）：① 灵石矿场景 ② 建造→产出 ③ 升级。交付标准：建筑产资源，升级加速。
> 本文档只描述设计，不包含代码。
> 状态：步骤 1–2、4、6 已实现（食物资源/HUD 灵米/开局赠送配置化；Building+BuildingManager 建造升级产出；BuildingsPanel 面板+资源按钮+暂停恢复），步骤 3 部分（建筑参数配置已加）、5 待实现

---

## 一、核心循环

```
建造（花灵石）→ 每日产出（灵石/食物）→ 攒资源升级 → 产出加速 → 支撑修炼/招募经济
```

- 纯挂机产出：与修炼/招募同节奏，监听 `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]` / `[food]` 配置节 + GameConfig 读取

| 项 | 内容 |
|----|------|
| 改动 | `game_config.cfg` 加两节（开局灵石/食物、灵石矿/灵田参数、口粮/饥饿参数）；`GameConfig.gd` 加对应字段 + `building_params` 字典 + 解析 |
| 验证 | 无头打印各配置值，缺项回退默认值 |

### 步骤 4：Building 模型 + BuildingManager

| 项 | 内容 |
|----|------|
| 改动 | `src/Sect/buildings/Building.gd`（type/level + 价格产出计算，运行时读配置）；`src/Sect/BuildingManager.gd`（建造/升级/每日产出/`buildings_changed` 信号）；`project.godot` 注册 Autoload |
| 验证 | 模拟：建造扣费入列、每日产出进 SectManager、升级后产出提升 |

### 步骤 5：口粮消耗 + 饥饿惩罚 + 断粮离宗

| 项 | 内容 |
|----|------|
| 改动 | `Disciple.gd` 加 `hunger_days`；`CultivationManager.gd` 每日先结算口粮（消耗→饥饿→离宗），`_gain_exp` 乘饥饿倍率 |
| 验证 | 模拟 40 天断粮：饥饿累计、修炼减半、第 30 天离宗、日志可见；恢复食物后清零 |

### 步骤 6：BuildingsPanel UI + "资源"按钮接线

| 项 | 内容 |
|----|------|
| 改动 | `src/UI/Panels/BuildingsPanel/`（面板场景+脚本，每类型一行：名称/等级/日产出+建造或升级按钮）；`TopBarHUD.tscn` 连"资源"按钮 → 新信号 → `MainGame.gd` 打开面板 |
| 验证 | 无头布局检查 + F5 手测：建造/升级/禁用态/暂停恢复 |

### 步骤 7：整体挂机验证 + 提交

| 项 | 内容 |
|----|------|
| 改动 | 无（仅验证） |
| 验证 | 挂机模拟：开局 500 灵石→建灵田→产出覆盖口粮→攒灵石升级→产出加速；断粮场景：不建灵田→30 天弟子离宗；对照八节验收清单逐项勾选 |

> 依赖关系：1→2 顺序执行（HUD 依赖食物资源）；3→4 顺序执行（Building 依赖配置）；5 依赖 1/3；6 依赖 4；7 为最终验证。

---

## 八、验收清单（D6 交付标准）

- [x] 新游戏开局赠送 500 灵石 + 100 食物（配置可调），HUD 可见
- [ ] 点"资源"按钮打开建筑面板（时间暂停，关闭恢复）
- [ ] 灵石充足时可建造灵石矿/灵田，扣费入列
- [ ] 每日自动产出灵石/食物，HUD 实时增长
- [ ] 升级建筑后产出提升（升级倍率生效），价格按倍率递增
- [ ] 灵石不足时建造/升级按钮禁用
- [ ] 等级达到上限后不可再升级
- [ ] 练气弟子每日消耗食物；断粮后饥饿天数累计、修炼速度减半
- [ ] 断粮累计 30 天弟子离宗（名录移除 + 日志）
- [ ] 食物恢复充足后饥饿清零
- [ ] 建筑/饥饿数据为纯数据（可序列化，D8 存档接入）

---

## 九、与后续任务衔接

| 后续任务 | 衔接方式 |
|----------|----------|
| D8 存档接入 | Building 纯数据模型直接序列化 |
| W3 财政经济 | 建筑产出进入收支流水；俸禄发放扣灵石 |
| W5 生产制造 | 灵田/灵石矿的弟子匹配度（灵根→效率）接入 |
| 修炼系统 | 后续灵气建筑（灵泉/聚灵阵）动态化 `qi_concentration` |