# 主世界与建筑模块设计

本文档定义主世界（hex 地块）、建筑与弟子派工的关系。背景见 `doc/WorldDesign.md`、`doc/P1模块拆分.md`。

## 1. 主世界方案（已定）

**正六边形单元格地图**，玩家在单元格上建设建筑/灵田（类似文明的领地经营 + 模拟经营的指派产出）。

### 1.1 设计咬合点（为什么用 hex）

- **灵石矿是地块资源**：哪块地有灵脉 → 占矿/买矿成为位置决策
- **秘境"在后山"是空间概念**：勘探发掘做成地图行为
- **后期地盘争夺需要地图**：从 P1 引入空间维度，后期不返工
- **成长可视化**："从小宗门到大宗门"= 地图从一小块山头扩大的过程

### 1.2 落地节奏（已定：坐标预留，渲染后置）

| 阶段 | 数据层 | UI 层 |
| --- | --- | --- |
| P1 | 建筑数据带 hex 坐标（axial） | 卡片/列表渲染，不做地图 |
| P2/P3 | 不变（存档天然带位置） | hex 主世界渲染（tile 美术 + 放置交互） |

前端后端分离下，UI 切换只影响显示层，后端零返工。

### 1.3 hex 成立的前提

1. **格子有位置价值**——灵脉格/水源格/肥沃地/岩石地，不同地块加成不同（纯装饰的格子不做）。
2. **地图随机生成**——每局资源分布不同，防止最优布局模板一劳永逸，保证复玩性。
3. **面积跟随成长**——开局只有山头几格，扩张需买地/开荒，地图与宗门成长绑定。

### 1.4 弟子与建筑的绑定深度（已定：派工单式）

- 弟子**指派**给建筑，月底结算产出，弟子不在地图上行走。
- 位置只影响加成（如灵田靠近水源产量+）。
- 明确不做实体行走式（寻路/队列/行程），与月回合结算节奏冲突，成本高。

## 2. 建筑实体模型

建筑（含灵田）是 hex 上的实体，**必须有弟子指派才有产出**：

```gdscript
## BuildingData.gd（RefCounted，纯数据）
var id: int
var cell: Vector2i          # hex axial 坐标（q, r）
var building_type: int      # 建筑类型枚举
var assigned_disciple_id: int = -1   # 指派弟子，-1 = 无
var progress: float = 0.0   # 生产/生长进度
var level: int = 1          # 建筑等级（预留）
```

## 3. 建筑类型

| 建筑 | 产出 | 指派要求 | 备注 |
| --- | --- | --- | --- |
| 外田（凡粮） | 灵稻 | 种植技艺 | 口粮来源 |
| 内田（灵药） | 聚气草/凝神花 | 种植技艺 | 炼丹原料 |
| 丹房 | 聚气丹/凝神丹 | 炼丹技艺 | 消耗灵药原料 |
| 仓库（预留） | — | — | 存粮/存料上限，后期 |
| 洞府/居所（预留） | — | — | 弟子数量上限，后期 |

P1 只做前三种（对应原 FieldManager + AlchemyManager 的职责，统一进建筑框架）。

## 4. 数据模型演进

原 `FieldData`（灵田）泛化为 `BuildingData`（建筑），灵田是建筑类型之一：

- 原 FieldManager → 建筑管理：地块放置、指派弟子、月度结算（生长/产出入库存）
- 种植类建筑带"作物"字段（作物类型/生长月数/品质），收获式产出
- 丹房是"即时加工"类建筑：有原料时弟子炼制入库存（也可保留 AlchemyManager 独立接口，两者皆可）

## 5. 月度结算信号流（不变）

```
settle_month()
  → 每个有弟子指派的建筑结算产出
    → 收获/成品入 InventoryManager
    → inventory_changed
```

## 6. 简化决策

| 完整愿景 | P1 取舍 | 后续 |
| --- | --- | --- |
| hex 地图渲染 | 不做，卡片/列表 | P2/P3 |
| 地图随机生成 | 固定初始地图（几块田+一丹房） | P3 |
| 地块地形差异 | 初始全默认，无加成 | P3 引入水源/灵脉 |
| 建筑多类型 | 只做外田/内田/丹房 | 逐里程碑加 |
| 弟子行走 | 不做（派工单式） | 不评估升级 |