# 开发说明书: 交互式品质生成器 (V5.1 - 最终补充版)

## 1. 核心概念

`CompInteractiveProducer` 是一个**主控制器**组件。它管理的建筑拥有一个统一的“生物质燃料”池。玩家可以通过**精确配置的燃料白/黑名单**，决定哪些物品可以作为燃料。

当玩家启动一个生产流程时，该流程会有一个**专属的、固定的总燃料消耗量**和**生产时间**。在生产过程中，组件会持续消耗燃料池，并根据燃料和温度的理想条件，计算最终产物的品质。

## 2. 架构设计

- **`CompInteractiveProducer` (控制器)**: 继承自 `ThingComp`，并实现 `IStoreSettingsParent`，负责所有逻辑。
- **`CompProperties_InteractiveProducer` (数据)**: 在 XML 中定义所有生产流程及其对应的参数，以及全局的燃料接受规则。

---
## 3. 依赖项说明

**重要**: 本组件的正常工作依赖于一个在 XML 中预先定义的 `JobDef`。交互菜单会尝试创建这个 Job 并分配给 Pawn。

**示例 `JobDef` 定义 (`Jobs.xml`):**
```xml
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
  <JobDef>
    <defName>ARA_IncubateJob</defName>
    <driverClass>ArachnaeSwarm.JobDriver_Incubate</driverClass>
    <reportString>正在启动生产 TargetA.</reportString>
    <allowOpportunisticPrefix>true</allowOpportunisticPrefix>
  </JobDef>
</Defs>
```
*注: `JobDriver_Incubate` 是一个简单的 JobDriver，其核心逻辑就是让 Pawn 走到建筑旁，然后调用 `comp.StartProduction(process)`。*

---

## 4. 实现步骤与完整代码

### **第 1 步: 定义支持精准配置的属性类**

**目的**: 创建 C# 类来映射新的、更详细的 XML 结构。

**产出代码 (属性类 V5):**
```csharp
// (代码与上一版相同，此处为简洁省略)
```

### **第 2 步: 实现完整的主组件**

**目的**: 编写最终的、包含所有新逻辑的 `CompInteractiveProducer` 类。

#### **代码解析与补充说明**

```csharp
// (此处为完整的 V5 版本 C# 代码)
// ...

// --- 交互与生产流程 ---
public override IEnumerable<FloatMenuOption> CompFloatMenuOptions(Pawn selPawn)
{
    // ...
    // **补充说明**: 此处创建的 Job "ARA_IncubateJob" 必须在 XML 中有对应定义。
    // 该 Job 的 Driver 应包含走到 parent 旁边，然后调用 StartProduction() 的逻辑。
    // ...
}

private void FinishProduction()
{
    // ...
    // **补充说明**: 最终品质的计算公式为：
    // finalQualityScore = Clamp01( (ticksUnderOptimalConditions / totalTicks) - temperaturePenaltyPercent )
    // 这意味着温度惩罚是直接从基础品质分中扣除的。
    // ...
}

private void ResetProduction() 
{
    // **补充说明**: 此方法会清空所有生产进度。
    // 如果玩家通过 Gizmo 中途取消，所有累积的“理想时间”和“温度惩罚”都会丢失。
    _selectedProcess = null;
    productionUntilTick = -1;
    ticksUnderOptimalConditions = 0;
    temperaturePenaltyPercent = 0f;
}

// --- 燃料系统方法 ---
private float GetNutritionInContainer() 
{
    // **性能备注**: 此方法会遍历容器。在绝大多数情况下性能良好。
    // 如果 Mod 允许容器内有成百上千的物品，可考虑增加缓存，不必每帧都计算。
    // ...
}
        
// --- IStoreSettingsParent & IThingHolder 实现 ---
// **说明**: 这些接口的实现让我们的组件能被游戏原生的运输和存储系统识别。
// GetStoreSettings() 暴露我们的配置，让小人知道可以运什么东西过来。
// GetDirectlyHeldThings() 暴露我们的内部容器，让游戏知道我们持有哪些物品。

// --- UI 与 Gizmos ---
public override string CompInspectStringExtra()
{
    // ...
    // **UI 设计补充**:
    // 生产中: 应清晰显示 "预计品质"，其计算公式为 (当前理想 tick 数 / 已进行 tick 数) - 当前温度惩罚。
    // 空闲时: 除了显示总燃料，还可增加一行提示，如 "可由 [白名单Pawn名称] 启动"。
    // ...
}

public override IEnumerable<Gizmo> GetGizmos()
{
    // ...
    // **Gizmo 设计补充**:
    // 取消按钮 (Command_Action) 的 action 应直接调用 ResetProduction()。
    // 可在开发者模式下增加调试按钮，如：
    // - "DEV: +10 营养"
    // - "DEV: 立即完成生产"
    // ...
}

public override void PostDestroy(DestroyMode mode, Map previousMap)
{
    base.PostDestroy(mode, previousMap);
    // **边缘情况处理**: 建筑被摧毁或卸载时，清空内部容器，
    // 默认情况下，容器内的物品会被丢弃在地上，这符合预期。
    innerContainer.TryDropAll(parent.Position, previousMap, ThingPlaceMode.Near);
}
```

---
这份 V5.1 版本的说明书，在 V5 的基础上，补充了对依赖项、UI细节、边缘情况和性能的考量，使其作为开发蓝图更加健壮和周全。这应该是我们开始编码前所需要的最终版本了。

## 5. 新增组件：温度损坏组件 (CompTemperatureRuinableDamage)

### 5.1 设计目标
创建一个新的组件，用于在极端温度下对物品造成持续伤害，并在温度恢复正常时逐渐恢复损坏进度。

### 5.2 组件属性类 (CompProperties_TemperatureRuinableDamage)
- `minSafeTemperature`: 安全温度范围的最低温度
- `maxSafeTemperature`: 安全温度范围的最高温度（默认100）
- `progressPerDegreePerTick`: 每度温度每tick造成的损坏进度（默认1E-05f）
- `damagePerTick`: 每tick造成的伤害值（默认1）
- `recoveryRate`: 温度恢复正常时的恢复速率（默认0.001f）

### 5.3 组件类 (CompTemperatureRuinableDamage)
- 继承自ThingComp，实现温度监控逻辑
- 当物品温度超出安全范围时，根据温度差值累积损坏进度，并每tick造成持续伤害
- 当温度恢复正常时，逐渐减少损坏进度而不是立即重置
- 支持保存和加载损坏进度状态

### 5.4 使用方法
在ThingDef的comps部分添加以下配置：
```xml
<li Class="ArachnaeSwarm.CompProperties_TemperatureRuinableDamage">
    <minSafeTemperature>13</minSafeTemperature>
    <maxSafeTemperature>28</maxSafeTemperature>
    <progressPerDegreePerTick>0.00005</progressPerDegreePerTick>
    <damagePerTick>1</damagePerTick>
    <recoveryRate>0.001</recoveryRate>
</li>
```