# 中央营养供给网络设计文档 (v2)

## 1. 概述

为了解决需要手动为大量建筑补充营养（燃料）的繁琐操作，本项目旨在设计并实现一个“中央营养供给网络”。该网络由一个或多个“中央供能塔”组成，它们能够自动、无线地为地图上所有需要营养的建筑进行补给。此外，系统还支持通过辅助建筑来提升供能塔的燃料传输效率。

## 2. 设计目标

*   **自动化**: 消除手动为每个建筑“加油”的需求。
*   **策略性**: 引入效率加成建筑，鼓励玩家进行更优化的基地布局。
*   **可扩展性**: 系统应支持多个供能塔、消费者和增效器建筑。
*   **性能友好**: 设计应考虑到性能，避免在游戏后期造成明显的卡顿。
*   **用户友好**: 玩家应能轻松理解网络的工作状态，并对其进行基本控制。

## 3. 系统架构

本系统采用**去中心化**的设计。每个“中央供能塔”都是一个独立的网络节点。同时，它也作为一个可以被其他设施影响的单位，以接收效率加成。

### 3.1. 主要组件与建筑

#### a. `CompNutrientNetworkFeeder` (供能塔核心组件)

*   **职责**:
    1.  **扫描与链接**: 定期扫描地图，查找所有在范围内的消费者建筑，并维护一个持久化的 `linkedConsumers` 列表。
    2.  **计算效率**: 检查自身 `Stat`，获取由“增效器”提供的 `NutrientTransmissionEfficiency` 总加成。
    3.  **分配与供能**: 从 `linkedConsumers` 列表中选择目标，计算需要补充的燃料量 `X`。根据效率加成，从自身燃料库中扣除 `X * (1 - EfficiencyBonus)` 的燃料。
    4.  **冲突避免**: 使用一个临时标记 `isBeingFueledNow` 来防止多个供能塔同时为一个目标补充。
    5.  **视觉效果**: 借鉴原版 `CompFacility`，在选中供能塔时，持续绘制到所有已连接消费者的连接线。
*   **依附于**: 中央供能塔 (`Building_NutrientTower`)。

#### b. `CompRefuelableNutrition` (修改现有组件)

*   **职责**:
    1.  **接收燃料**: 增加一个新的公共方法 `ReceiveFuelFromNetwork(float amount)`。
    2.  **状态标记**: 增加一个临时的 `bool isBeingFueledNow` 字段。

#### c. “营养网络增效器” (新建筑)
*   **`ThingDef`**: 一个新的建筑，例如 `ARA_NutrientNetworkBooster`。
*   **`comps`**:
    *   拥有 `<li Class="CompProperties_Facility">`。
    *   在 `statOffsets` 中提供一个新的 `StatDef` 加成：`<NutrientTransmissionEfficiency>0.1</NutrientTransmissionEfficiency>`。

#### d. “中央供能塔” (修改)
*   **`comps`**:
    *   除了原计划的组件，新增 `<li Class="CompProperties_AffectedByFacilities">`，使其可以链接到“增效器”。

### 3.2. 工作流程 (Mermaid)

```mermaid
graph TD
    subgraph "增效器 (Booster)"
        C(Building_Booster)
        C -- 提供加成 --> B
    end

    subgraph "中央供能塔 (Provider)"
        B(Building_NutrientTower)
        B -- 拥有 --> B1[CompAffectedByFacilities]
        B -- 拥有 --> B2[CompNutrientNetworkFeeder]
    end

    subgraph "消费者建筑 (Consumer)"
        A(Building_Existing)
    end

    B2 -- 1. 扫描并连接 --> A
    B2 -- 2. 选中时绘制连接线 --> A
    C -- "statOffsets" --> B1
    B2 -- 3. 从B1读取效率加成 --> B1
    B2 -- 4. 根据效率进行供能 --> A
```

## 4. 实现细节与挑战

*   **自定义StatDef**: 需要在XML中创建一个新的 `StatDef`，名为 `NutrientTransmissionEfficiency`。
*   **性能优化**: 保持合理的扫描间隔。
*   **范围限制**: 供能塔的服务范围和增效器的影响范围都应是可配置的。
*   **视觉反馈**:
    *   供能塔 -> 消费者：绘制连接线，颜色可根据消费者燃料状态变化。
    *   增效器 -> 供能塔：使用原版的 `CompFacility` 机制，在选中增效器时会自动显示其影响的供能塔。

## 5. XML 定义 (示例)

#### a. 新的 StatDef
```xml
<StatDef>
  <defName>NutrientTransmissionEfficiency</defName>
  <label>nutrient transmission efficiency</label>
  <description>Reduces the amount of fuel consumed when transfering nutrients wirelessly. The final cost is multiplied by (1 - efficiency).</description>
  <category>Building</category>
  <defaultBaseValue>0</defaultBaseValue>
  <minValue>0</minValue>
  <toStringStyle>PercentZero</toStringStyle>
</StatDef>
```

#### b. 增效器 ThingDef
```xml
<ThingDef ParentName="BuildingBase">
  <defName>ARA_NutrientNetworkBooster</defName>
  <!-- ...其他属性... -->
  <comps>
    <li Class="CompProperties_Facility">
      <linkableBuildings>
        <li>ARA_NutrientNetworkTower</li>
      </linkableBuildings>
      <statOffsets>
        <NutrientTransmissionEfficiency>0.1</NutrientTransmissionEfficiency>
      </statOffsets>
    </li>
  </comps>
</ThingDef>
```

#### c. 供能塔 ThingDef
```xml
<ThingDef ParentName="BuildingBase">
  <defName>ARA_NutrientNetworkTower</defName>
  <!-- ...其他属性... -->
  <comps>
    <li Class="CompProperties_RefuelableNutrition">...</li>
    <li Class="ArachnaeSwarm.CompProperties_NutrientNetworkFeeder">...</li>
    <li Class="CompProperties_AffectedByFacilities">
      <linkableFacilities>
        <li>ARA_NutrientNetworkBooster</li>
      </linkableFacilities>
    </li>
    <!-- ...Flickable, Breakdownable, Power... -->
  </comps>
</ThingDef>
```

---
这份文档现在包含了我们所有的设计决策，形成了一个完整且强大的功能蓝图。