Files
ArachnaeSwarm/Source/Documents/AnimalWorkModeSolution_Final_Implementation.md
2025-09-02 21:28:25 +08:00

514 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 动物工作模式解决方案文档(最终实现版)
## 1. 项目概述
本项目旨在实现一个功能,使动物(特别是昆虫)能够像机械体一样持续工作,而不需要通过机械师控制 WorkMode。通过为动物启用工作系统并创建自定义行为树动物将始终处于工作状态持续执行允许的工作类型。
## 2. 原版代码分析
### 2.1 昆虫 ThinkTreeDef 结构
原版昆虫的 ThinkTree (`Insect.xml`) 包含以下主要逻辑:
1. **紧急情况处理**:倒地、燃烧、精神状态等
2. **基本需求满足**:睡觉、吃饭等
3. **驯服动物行为**:跟随主人、救援等
4. **闲置行为**:漫游、待命等
### 2.2 机械体 ThinkTreeDef 结构
原版机械体的 ThinkTree (`Mechanoid.xml`) 包含 WorkMode 系统,这是动物不具备的。
## 3. 为什么机械体有 workSettings 而动物没有
### 3.1 核心原因分析
机械体和动物虽然都是 Pawn但它们的 workSettings 初始化逻辑不同:
1. **`Pawn_WorkSettings` 的存在性**
- `Pawn` 类内部持有一个 `Pawn_WorkSettings` 类型的引用 `priorities`,默认为 `null`
- `public bool EverWork => priorities != null;` 属性表明只有当 `priorities` 不为 `null`Pawn 才有工作能力
2. **初始化条件**
- `EnableAndInitializeIfNotAlreadyInitialized()` 方法检查 `priorities` 是否为 `null`,如果为 `null` 则调用 `EnableAndInitialize()`
- `EnableAndInitialize()` 方法是真正执行初始化的地方,创建 `priorities` 对象并根据条件设置初始优先级
3. **Mechanoid 有 WorkSettings 的证据**
- `EnableAndInitialize()` 方法明确包含对机械体的特殊处理:
```csharp
if (ModsConfig.BiotechActive && pawn.RaceProps.IsMechanoid && !pawn.RaceProps.mechWorkTypePriorities.NullOrEmpty())
{
for (int i = 0; i < pawn.RaceProps.mechWorkTypePriorities.Count; i++)
{
MechWorkTypePriority mechWorkTypePriority = pawn.RaceProps.mechWorkTypePriorities[i];
SetPriority(mechWorkTypePriority.def, mechWorkTypePriority.priority);
}
}
```
- 这表明机械体的设计意图就是拥有并使用 `Pawn_WorkSettings`
4. **Animal 没有 WorkSettings 的证据**
- **直接初始化逻辑**`EnableAndInitialize()` 方法在为 Pawn 分配默认"活跃"工作类型时,会过滤掉 `pawn.WorkTypeIsDisabled(w)` 的工作类型。对于大多数动物来说,它们的 `RaceProps` 会禁用几乎所有需要手动分配的 `WorkTypeDef`
- **工作类型的定义**:绝大多数工作类型都包含限制,使得动物 Pawn 默认无法执行这些工作
- **特定工作提供者的处理**:针对动物的操作是通过独立的 `WorkGiver` 系统直接处理的,不依赖于通用的 `workSettings` 优先级系统
### 3.2 结论
机械体被设计为拥有 `Pawn_WorkSettings`,因为它们的工作优先级可以通过其 `RaceProps.mechWorkTypePriorities` 进行预设,并且游戏逻辑会在需要时初始化它。
动物通常没有有效的 `Pawn_WorkSettings`,因为:
1. 它们被设计为不能执行绝大多数需要手动分配的工作
2. 它们与玩家互动的特定工作是通过独立的 `WorkGiver` 系统直接处理的
3. 因此,除非有特定的游戏逻辑或 Mod 显式地为动物调用 `EnableAndInitialize()`,否则它们的 `priorities` 对象很可能保持 `null` 状态
## 4. 为什么 `RaceProps.mechWorkTypePriorities` 只对机械体有效
### 4.1 核心解释
`mechWorkTypePriorities` 是 `RaceProperties` 类中的一个字段专门用于定义机械体Mechanoid在生成时其工作类型Work Types的默认优先级。它的设计和使用都与机械体的独特机制紧密相关而这些机制在动物或其他生物上并不存在或不以相同方式运作。
### 4.2 详细证据和解释
1. **字段定义与命名**
- `mechWorkTypePriorities` 被明确定义为:
```csharp
public List<MechWorkTypePriority> mechWorkTypePriorities;
```
- 其名称 `mechWorkTypePriorities` 包含了 "Mech" 前缀,明确指示其用途是针对机械体的。
2. **`MechWorkTypePriority` 类型**
- 该字段存储的是 `MechWorkTypePriority` 对象的列表。虽然代码片段中没有直接给出 `MechWorkTypePriority` 的定义,但其名称和用途(存储工作类型及其优先级)强烈暗示它是专门为机械体设计的数据结构。
3. **使用场景 - 初始化工作设置**
- 关键证据出现在 `Pawn_WorkSettings.EnableAndInitialize()` 方法中:
```csharp
// ... (其他初始化代码) ...
if (ModsConfig.BiotechActive && pawn.RaceProps.IsMechanoid && !pawn.RaceProps.mechWorkTypePriorities.NullOrEmpty())
{
for (int i = 0; i < pawn.RaceProps.mechWorkTypePriorities.Count; i++)
{
MechWorkTypePriority mechWorkTypePriority = pawn.RaceProps.mechWorkTypePriorities[i];
SetPriority(mechWorkTypePriority.def, mechWorkTypePriority.priority);
}
}
// ... (其他初始化代码,如处理禁用的工作类型) ...
```
- 这段代码明确地检查了三个条件:
* `ModsConfig.BiotechActive`生物技术Biotech模组是否激活。这表明该功能是与 Biotech 模组引入的机械体相关的。
* `pawn.RaceProps.IsMechanoid`:当前 Pawn单位的种族属性是否为机械体。
* `!pawn.RaceProps.mechWorkTypePriorities.NullOrEmpty()`:该机械体的 `mechWorkTypePriorities` 列表是否存在且非空。
- **只有当这三个条件都满足时,才会遍历 `mechWorkTypePriorities` 列表,并根据其中定义的 `WorkTypeDef` 和优先级来设置该机械体 Pawn 的工作优先级。**
- 对于动物或其他非机械体生物,`pawn.RaceProps.IsMechanoid` 条件为假,因此即使在它们的 `ThingDef` 中定义了 `mechWorkTypePriorities`,这段代码也不会执行,这些优先级设置就会被忽略。
4. **机制差异 - 动物 vs 机械体**
- **动物**:动物的工作能力(如驯服、训练、特定任务)通常是通过 `trainability`(可训练性)、`trainableTags`(可训练标签)等属性来定义的。它们的工作行为(如觅食、繁殖、战斗)主要由其 `intelligence`(智力)、`thinkTreeMain`(主思考树)和 `dutyBoss`(职责)等属性驱动。它们的初始工作优先级(如果有的话)通常是固定的或基于简单规则随机分配,而不是通过一个专门的优先级列表来精确控制。
- **机械体**:机械体是 Biotech 模组引入的复杂单位,它们拥有类似殖民者的工作系统。它们可以被指派执行各种殖民者能做的工作(如建造、种植、烹饪等),其能力范围和初始工作优先级需要更精细的控制。`mechWorkTypePriorities` 就是为了满足这种需求而设计的,允许设计者为每种机械体明确指定哪些工作类型应该默认开启以及它们的优先级。
5. **辅助证据 - MechWorkUtility**
- 在 `MechWorkUtility` 类中,多个方法(如 `SpecialDisplayStats`, `AnyWorkMechCouldDo`)在处理与机械体工作相关逻辑时,都会首先检查 `parentDef.race.IsMechanoid`。这进一步证明了与机械体工作类型相关的逻辑是严格限定于机械体的。
### 4.3 结论
`RaceProperties.mechWorkTypePriorities` 虽然是 `RaceProperties` 类的一个通用属性,但它被设计并实现为**仅对机械体Mechanoid生效**。这是因为:
1. 它的命名和数据类型 (`MechWorkTypePriority`) 明确指向机械体。
2. 核心的使用代码 (`Pawn_WorkSettings.EnableAndInitialize`) 通过 `pawn.RaceProps.IsMechanoid` 条件严格限制了其应用范围。
3. 机械体和动物在工作系统上的根本差异决定了需要不同的机制来管理其初始工作能力,`mechWorkTypePriorities` 是为满足机械体特有需求而生的。
因此,即使在动物的 `ThingDef` 文件中添加了 `mechWorkTypePriorities` 部分,游戏代码也不会读取或应用这些设置,因为动物不是机械体,相关的初始化逻辑不会被执行。
## 5. 通过 Harmony 补丁拦截 `pawn.RaceProps.IsMechanoid` 的分析
### 5.1 用户提供的实现思路
用户提供了一种更精确和安全的实现思路:通过 Harmony 补丁拦截 `Pawn_WorkSettings.EnableAndInitialize` 方法,在特定条件下局部伪装成机械体来为动物启用工作系统。
### 5.2 实现方法
1. **引入 Harmony**:确保你的 Mod 项目中引用了 Harmony 库。
2. **定义补丁类**:创建一个静态类来存放你的 Harmony 补丁。
3. **编写前缀补丁**
```csharp
[HarmonyPatch(typeof(Pawn_WorkSettings), nameof(Pawn_WorkSettings.EnableAndInitialize))]
public static class Patch_Pawn_WorkSettings_EnableAndInitialize
{
public static bool Prefix(Pawn_WorkSettings __instance, Pawn ___pawn)
{
// 检查是否是我们想要启用工作系统的动物
if (___pawn.Faction != null && ___pawn.Faction.IsPlayer &&
!___pawn.RaceProps.IsMechanoid && // 真实身份不是机械体
ShouldEnableWorkSystem(___pawn)) // 但我们需要为它启用工作系统
{
// 局部伪装成机械体来执行初始化逻辑
// 执行机械体工作优先级初始化逻辑
if (ModsConfig.BiotechActive && !___pawn.RaceProps.mechWorkTypePriorities.NullOrEmpty())
{
for (int i = 0; i < ___pawn.RaceProps.mechWorkTypePriorities.Count; i++)
{
var priority = ___pawn.RaceProps.mechWorkTypePriorities[i];
__instance.SetPriority(priority.def, priority.priority);
}
}
// 同时也可以初始化 mechEnabledWorkTypes 中的工作类型
if (!___pawn.RaceProps.mechEnabledWorkTypes.NullOrEmpty())
{
foreach (var workType in ___pawn.RaceProps.mechEnabledWorkTypes)
{
if (!__instance.WorkIsActive(workType) && !___pawn.WorkTypeIsDisabled(workType))
{
__instance.SetPriority(workType, 3); // 默认优先级
}
}
}
// 阻止原方法继续执行
return false;
}
return true; // 其他情况正常执行原逻辑
}
private static bool ShouldEnableWorkSystem(Pawn pawn)
{
// 检查是否有特定的 Comp
if (pawn.TryGetComp<CompWorkForNonMechs>() != null)
return true;
// 检查是否有 mechWorkTypePriorities 或 mechEnabledWorkTypes 配置
if (!pawn.RaceProps.mechWorkTypePriorities.NullOrEmpty() ||
!pawn.RaceProps.mechEnabledWorkTypes.NullOrEmpty())
return true;
return false;
}
}
```
4. **应用补丁**
```csharp
[StaticConstructorOnStartup]
public static class AnimalWorkSystemPatcher
{
static AnimalWorkSystemPatcher()
{
var harmony = new Harmony("com.yourname.animalworksystem");
harmony.PatchAll();
}
}
```
### 5.3 潜在问题和风险
1. **副作用**
- 这种方法比直接补丁 `IsMechanoid` 属性更加精确,因为它只在 `Pawn_WorkSettings.EnableAndInitialize` 方法中进行伪装,不影响其他系统。
- 但仍需注意确保伪装逻辑只在特定条件下触发,避免意外影响其他 Pawn。
2. **补丁冲突**
- 其他 Mod 也可能使用 Harmony 来修改 `Pawn_WorkSettings` 或相关逻辑。
- 需要确保补丁逻辑具有良好的兼容性。
3. **性能影响**
- Harmony 补丁会增加方法调用的开销,但在这个场景下影响很小。
4. **维护困难**
- 如果游戏更新修改了相关逻辑,你的补丁可能失效或产生新的问题,需要随之更新。
### 5.4 结论和建议
用户提供的实现思路是一种更加精确和安全的方法,通过局部伪装成机械体来为动物启用工作系统。这种方法的优点包括:
1. **精确性**:只在特定条件下(动物是玩家阵营且需要启用工作系统)才进行伪装。
2. **安全性**:只在 `Pawn_WorkSettings.EnableAndInitialize` 方法中进行伪装,不影响其他系统。
3. **兼容性**:通过检查特定的 Comp 或配置来决定是否启用工作系统,具有良好的可扩展性。
## 6. 完整实现方案
### 6.1 核心思路
1. 为动物添加 `CompWorkForNonMechs` 以启用工作系统
2. 创建 `ThinkNode_AnimalWorker` 替代默认行为,强制工作
3. 使用 Harmony 补丁局部伪装成机械体来为动物启用工作系统
4. 使用自定义 ThinkTree 替代默认动物行为树
5. 定义允许的工作类型,并确保其与 WorkGiver 兼容
### 6.2 设计要点
1. **为动物启用 WorkSettings 系统**:通过 Harmony 补丁局部伪装成机械体来为动物启用工作系统
2. **使用自定义 ThinkNode 强制工作行为**:创建 ThinkNode跳过所有动物默认行为直接进入工作逻辑
3. **修改动物定义**:添加 ThinkTree 和 Comp
4. **为动物添加工作类型支持**:定义允许的工作类型
## 7. 实现细节
### 7.1 CompWorkForNonMechs.cs
```csharp
using System.Collections.Generic;
using RimWorld;
using Verse;
namespace YourModName
{
public class CompWorkForNonMechs : ThingComp
{
public class CompProperties_WorkForNonMechs : CompProperties
{
public List<WorkTypeDef> workTypes;
public CompProperties_WorkForNonMechs()
{
compClass = typeof(CompWorkForNonMechs);
}
}
public override void PostSpawnSetup(bool respawningAfterLoad)
{
base.PostSpawnSetup(respawningAfterLoad);
var pawn = parent as Pawn;
if (pawn == null || pawn.Faction == null || !pawn.Faction.IsPlayer) return;
// 启用工作设置
if (pawn.workSettings == null)
{
pawn.workSettings = new Pawn_WorkSettings(pawn);
}
pawn.workSettings.EnableAndInitialize();
// 启用指定的工作类型
var props = (CompProperties_WorkForNonMechs)props;
if (props.workTypes != null)
{
foreach (var workType in props.workTypes)
{
if (!pawn.WorkTypeIsDisabled(workType))
{
pawn.workSettings.SetPriority(workType, 3); // 默认优先级
}
}
}
}
}
}
```
### 7.2 ThinkNode_AnimalWorker.cs
```csharp
using RimWorld;
using Verse;
namespace YourModName
{
public class ThinkNode_AnimalWorker : ThinkNode_Priority
{
public override ThinkResult TryIssueJobPackage(Pawn pawn, JobIssueParams jobParams)
{
if (pawn.workSettings == null || !pawn.Faction.IsPlayer)
{
return ThinkResult.NoJob;
}
// 优先执行紧急工作
var job = WorkGiverUtility.GetPriorityWork(pawn, emergency: true);
if (job != null) return new ThinkResult(job, this);
// 然后执行普通工作
job = WorkGiverUtility.GetPriorityWork(pawn, emergency: false);
if (job != null) return new ThinkResult(job, this);
return ThinkResult.NoJob;
}
}
}
```
### 7.3 AnimalWorkSystemPatcher.cs
```csharp
using System.Collections.Generic;
using System.Reflection;
using HarmonyLib;
using RimWorld;
using Verse;
namespace YourModName
{
[StaticConstructorOnStartup]
public static class AnimalWorkSystemPatcher
{
static AnimalWorkSystemPatcher()
{
var harmony = new Harmony("com.yourname.animalworksystem");
harmony.PatchAll();
}
}
[HarmonyPatch(typeof(Pawn_WorkSettings), nameof(Pawn_WorkSettings.EnableAndInitialize))]
public static class Patch_Pawn_WorkSettings_EnableAndInitialize
{
// 缓存原始的 IsMechanoid 属性 Getter
private static PropertyInfo isMechanoidProperty =
typeof(RaceProperties).GetProperty("IsMechanoid", BindingFlags.Public | BindingFlags.Instance);
public static bool Prefix(Pawn_WorkSettings __instance, Pawn ___pawn)
{
// 检查是否是我们想要启用工作系统的动物
if (___pawn.Faction != null && ___pawn.Faction.IsPlayer &&
!___pawn.RaceProps.IsMechanoid && // 真实身份不是机械体
ShouldEnableWorkSystem(___pawn)) // 但我们需要为它启用工作系统
{
// 局部伪装成机械体来执行初始化逻辑
// 执行机械体工作优先级初始化逻辑(来自 Pawn_WorkSettings.EnableAndInitialize
if (ModsConfig.BiotechActive && !___pawn.RaceProps.mechWorkTypePriorities.NullOrEmpty())
{
for (int i = 0; i < ___pawn.RaceProps.mechWorkTypePriorities.Count; i++)
{
var priority = ___pawn.RaceProps.mechWorkTypePriorities[i];
__instance.SetPriority(priority.def, priority.priority);
}
}
// 同时也可以初始化 mechEnabledWorkTypes 中的工作类型(如果你需要)
if (!___pawn.RaceProps.mechEnabledWorkTypes.NullOrEmpty())
{
foreach (var workType in ___pawn.RaceProps.mechEnabledWorkTypes)
{
if (!__instance.WorkIsActive(workType) && !___pawn.WorkTypeIsDisabled(workType))
{
__instance.SetPriority(workType, 3); // 默认优先级
}
}
}
// 阻止原方法继续执行(因为我们已经手动处理了初始化)
return false;
}
return true; // 其他情况正常执行原逻辑
}
private static bool ShouldEnableWorkSystem(Pawn pawn)
{
// 你可以通过多种方式判断:
// 1. 检查是否有特定的 Comp
if (pawn.TryGetComp<CompWorkForNonMechs>() != null)
return true;
// 2. 检查是否有 mechWorkTypePriorities 或 mechEnabledWorkTypes 配置
if (!pawn.RaceProps.mechWorkTypePriorities.NullOrEmpty() ||
!pawn.RaceProps.mechEnabledWorkTypes.NullOrEmpty())
return true;
// 3. 检查特定的标签或 defName
// return pawn.def.defName.Contains("Worker");
return false;
}
}
}
```
### 7.4 修改动物定义
```xml
<ThingDef ParentName="BaseInsect">
<defName>Megascarab_Worker</defName>
<label>worker megascarab</label>
<description>A genetically modified megascarab, capable of performing simple mechanical tasks.</description>
<statBases>
<MoveSpeed>3.0</MoveSpeed>
<MarketValue>300</MarketValue>
</statBases>
<race>
<thinkTreeMain>InsectWorker</thinkTreeMain>
<thinkTreeConstant>AnimalConstant</thinkTreeConstant>
<mechWorkTypePriorities>
<li>
<def>Hauling</def>
<priority>3</priority>
</li>
<li>
<def>Cleaning</def>
<priority>2</priority>
</li>
</mechWorkTypePriorities>
</race>
<comps>
<li Class="YourModName.CompWorkForNonMechs+CompProperties_WorkForNonMechs">
<workTypes>
<li>Hauling</li>
<li>Cleaning</li>
<li>BasicWorker</li>
</workTypes>
</li>
</comps>
</ThingDef>
```
### 7.5 自定义 ThinkTreeDef
```xml
<ThinkTreeDef>
<defName>InsectWorker</defName>
<thinkRoot Class="ThinkNode_Priority">
<subNodes>
<!-- 紧急情况处理 -->
<li Class="ThinkNode_Subtree"><treeDef>Downed</treeDef></li>
<li Class="ThinkNode_Subtree"><treeDef>BurningResponse</treeDef></li>
<li Class="ThinkNode_Subtree"><treeDef>MentalStateCritical</treeDef></li>
<!-- 强制工作模式 -->
<li Class="YourModName.ThinkNode_AnimalWorker" />
<!-- 闲置行为 -->
<li Class="JobGiver_IdleError"/>
</subNodes>
</thinkRoot>
</ThinkTreeDef>
```
## 8. 原始方案的反驳分析
### 8.1 项目概述:不成立
**反驳证据:**
- RimWorld 原版设计中,动物的行为树是完全独立于机械体的,没有 WorkMode 系统。
- 动物不能直接复用机械体的工作逻辑。
### 8.2 ThinkNode_AnimalAlwaysWork 类:不成立
**反驳证据:**
- `ThinkNode_Priority` 是一个标准的 ThinkNode它会按顺序尝试子节点直到某一个返回 `ThinkResult`。
- 该类不会实现"始终工作"的功能,因为它没有改变行为树的执行逻辑。
### 8.3 InsectWorker ThinkTreeDef不成立
**反驳证据:**
- RimWorld 中,动物的 ThinkTree 并不会调用 `JobGiver_Work`,因为该类是为机械体设计的。
- 即使强制插入 `JobGiver_Work`,它也会因为动物的 `WorkSettings` 未初始化而失败。
### 8.4 Harmony 补丁拦截 IsMechanoid不成立
**反驳证据:**
- `RaceProperties.IsMechanoid` 是一个只读属性,由 `<race><isMechanoid>true</isMechanoid></race>` 控制。
- Patch 该属性会导致所有依赖该属性的逻辑被干扰,风险极高。
## 9. 使用说明
1. **编译代码**:将所有 C# 文件编译到您的 Mod 中
2. **添加 XML 文件**:将新的 ThinkTreeDef 和动物定义添加到您的 Mod 中
3. **配置工作类型**:在动物定义中配置 `mechWorkTypePriorities` 和 `CompWorkForNonMechs` 组件
4. **测试**:在游戏中生成修改后的动物,观察其工作行为
## 10. 注意事项
1. **兼容性**:此方案绕过了 WorkMode 系统,动物将始终处于工作状态
2. **性能**:频繁的工作查找可能会有轻微性能影响
3. **调试**:如果遇到问题,请检查日志文件中的错误信息
4. **避免 patch IsMechanoid**:不干扰原版逻辑
5. **副作用风险**:直接 patch `IsMechanoid` 会导致严重的副作用,强烈不推荐使用
6. **精确补丁**:用户提供的实现通过局部伪装成机械体来为动物启用工作系统,是一种更加精确和安全的方法