1. 项目概述与核心价值

如果你玩过《边缘世界》（RimWorld），并且对游戏里那些依赖天气、动不动就罢工的太阳能板感到又爱又恨，那你可能已经动过自己动手改一改的念头。这个项目，就是带你从零开始，用C#代码亲手“复刻”一个属于你自己的太阳能发电机Mod。这不仅仅是复制一个游戏内物品，而是深入理解RimWorld Mod开发的核心逻辑，从动态发电计算、环境遮挡检测到游戏UI的绘制，完整走一遍一个功能型建筑Mod的开发全流程。

我之所以选择太阳能发电机作为切入点，是因为它麻雀虽小，五脏俱全。它涉及了RimWorld Mod开发的几个关键层面：Thing（物品/建筑）定义、Comp（组件）逻辑、GameCondition（游戏条件）交互以及Gizmo（命令工具）的绘制。通过实现它，你能系统地掌握如何让一段C#代码“活”在游戏世界里，响应昼夜交替、天气变化，并与玩家进行交互。网上很多教程只讲“怎么做”，但踩坑的经验往往一笔带过。这篇指南会聚焦在那些容易出错的“坑点”上，比如如何正确处理Tick（游戏刻）更新以避免性能问题，如何精准计算遮挡率，以及如何让自定义的Gizmo（命令工具）既美观又实用。最终，你会得到一套可以直接编译、运行，并且能在此基础上自由扩展的完整源码。

2. 开发环境准备与项目结构搭建

2.1 工具链选择与配置

工欲善其事，必先利其器。RimWorld Mod开发主要依赖以下工具：

1. Visual Studio 2022：社区版完全免费，对C#和.NET开发支持最好。确保安装“.NET 桌面开发”和“使用C++的桌面开发”工作负载。
2. RimWorld游戏本体：这是我们的“运行时环境”和API来源。建议使用Steam版本，便于管理。
3. RimWorld Mod开发环境：本质上，我们是创建一个符合RimWorld Mod结构的C#类库项目。你需要引用游戏目录下的核心程序集，主要是Assembly-CSharp.dll（位于RimWorld\RimWorldWin64_Data\Managed\）。

这里有个大坑：不要直接引用游戏目录下的DLL文件。因为游戏更新时，这些文件会被覆盖。正确的做法是，在Visual Studio中创建一个新的“类库（.NET Framework）”项目，目标框架版本选择与游戏匹配的（例如RimWorld 1.4通常对应.NET Framework 4.7.2）。然后，将这些必要的DLL文件（如Assembly-CSharp.dll,UnityEngine.CoreModule.dll等）复制到你的项目目录下一个单独的Libs文件夹中，再从那里添加引用。这样，你的项目依赖就与游戏本体解耦了。

2.2 项目结构与Mod清单

一个标准的RimWorld Mod目录结构如下：

MySolarGeneratorMod/ ├── About/ │ └── About.xml # Mod元数据，名称、描述、作者等 ├── Assemblies/ │ └── MySolarGeneratorMod.dll # 我们编译的C#程序集 ├── Defs/ # XML定义文件 │ ├── ThingDefs/ # 物品/建筑定义 │ ├── ResearchDefs/ # 研究项目定义（如果需要） │ └── ... ├── Languages/ # 多语言支持 │ └── ChineseSimplified/ │ └── Keyed/ │ └── Strings.xml ├── Textures/ # 纹理图片 │ └── Buildings/ │ └── SolarGenerator.png └── Source/ # （可选）C#源代码目录，方便分享

About.xml是Mod的身份证，其内容至关重要：

<?xml version="1.0" encoding="utf-8"?> <ModMetaData> <name>自定义太阳能发电机</name> <author>你的名字</author> <packageId>YourName.ModName</packageId> <!-- 必须全局唯一，通常用作者.模组名格式 --> <supportedVersions> <li>1.4</li> </supportedVersions> <description>一个复刻并增强了逻辑的太阳能发电机。</description> <loadAfter> <li>UnlimitedHugs.HugsLib</li> <!-- 如果依赖其他Mod，在此声明 --> </loadAfter> </ModMetaData>

避坑点1：packageId的格式。它不能包含空格，最好使用点号分隔，且在整个Steam创意工坊中应保持唯一，否则会导致Mod冲突或无法订阅。

3. 核心逻辑设计与C#类结构

3.1 理解RimWorld的能源系统与Tick机制

在RimWorld中，电力是一个核心资源。发电建筑（如风力涡轮机、地热发电机）通过一个名为CompPowerPlant的组件（Component）来工作。我们的太阳能发电机也将继承这个体系。但太阳能有其特殊性：它的输出不是恒定的，而是随时间（昼夜）和空间（遮挡）变化的。

这里涉及RimWorld一个基础概念：Tick。游戏世界每秒进行60次逻辑更新，即60 TPS。大部分逻辑代码（如我们的发电计算）会在每个Tick或每若干个Tick被执行一次。直接在Tick()方法里进行复杂的计算（如遍历所有地图格子检查遮挡）是性能灾难。我们必须采用缓存和分帧计算的策略。

3.2 设计自定义组件CompPowerPlantSolar

我们将创建一个新的组件类CompPowerPlantSolar，继承自CompPowerPlant。这是实现动态发电逻辑的核心。

using RimWorld; using Verse; namespace MySolarGeneratorMod { public class CompPowerPlantSolar : CompPowerPlant { // 基础属性：最大理论发电量（瓦） public float MaxOutputWatts = 1700f; // 当前输出效率（0.0 - 1.0），受昼夜和遮挡影响 private float curEfficiency = 0f; // 遮挡率（0.0 - 1.0），1.0表示完全被遮挡 private float roofCoverage = 0f; // 缓存上一次计算遮挡的时间戳（Tick数），避免每帧计算 private int lastCoverageCheckTick = -99999; // 遮挡检查间隔（Tick数），例如每250 Tick检查一次（约4.17秒） private const int CoverageCheckInterval = 250; // 核心属性：当前实际发电量 = 最大输出 * 当前效率 public override float DesiredPowerOutput { get { // 如果父建筑（太阳能板）被损坏或未通电，则不发电 if (parent.Map == null || parent.Destroyed || !parent.Spawned || !FlickUtility.WantsToBeOn(parent)) { return 0f; } return MaxOutputWatts * curEfficiency; } } // 每Tick更新的逻辑 public override void CompTick() { base.CompTick(); // 调用父类基础逻辑 UpdateEfficiency(); } // 更新效率的核心方法 private void UpdateEfficiency() { // 1. 计算昼夜效率（基于游戏时间） float dayNightEfficiency = CalculateDayNightEfficiency(); // 2. 定期更新遮挡率（非每Tick） if (Find.TickManager.TicksGame >= lastCoverageCheckTick + CoverageCheckInterval) { UpdateRoofCoverage(); lastCoverageCheckTick = Find.TickManager.TicksGame; } // 3. 综合计算最终效率：昼夜效率 * (1 - 遮挡率) // 假设遮挡物（如屋顶、山体）会完全阻挡阳光 curEfficiency = dayNightEfficiency * (1f - roofCoverage); // 4. 通知电网更新功率（重要！） if (powerComp != null) { powerComp.PowerOutput = DesiredPowerOutput; } } // 计算基于游戏内时间的效率（正弦曲线模拟日出日落） private float CalculateDayNightEfficiency() { // 获取当前地图的游戏时间管理器 Map map = parent.Map; if (map == null) return 0f; // GenLocalDate.DayPercent 返回当前游戏日内的时间进度（0.0午夜，0.5正午） float dayPercent = GenLocalDate.DayPercent(map); // 使用平滑的曲线模拟太阳高度角，正午效率最高（1.0），午夜为0 // 这里使用正弦函数的一个区间，并限制在0-1之间 // 将一天的时间（0-1）映射到正弦函数的 -π/2 到 3π/2 区间，取sin值并归一化 float rawEfficiency = Mathf.Sin(dayPercent * Mathf.PI * 2f - Mathf.PI / 2f); // 将sin值从[-1, 1]映射到[0, 1] rawEfficiency = (rawEfficiency + 1f) / 2f; // 进一步平滑，避免日出日落时效率变化过于突兀 rawEfficiency = Mathf.SmoothStep(0f, 1f, rawEfficiency); // 考虑天气影响：雨天、雾天降低效率 if (map.weatherManager.RainRate > 0.1f) { rawEfficiency *= 0.3f; // 雨天效率降至30% } else if (map.weatherManager.FogRate > 0.5f) { rawEfficiency *= 0.7f; // 浓雾效率降至70% } return Mathf.Clamp01(rawEfficiency); } // 更新屋顶/山体遮挡率 private void UpdateRoofCoverage() { if (parent.Map == null) return; // 获取太阳能板占据的格子（假设是3x3的建筑） CellRect occupiedRect = parent.OccupiedRect(); int totalCells = occupiedRect.Area; int roofedCells = 0; // 遍历所有被占据的格子，检查是否有屋顶或 overhead mountain（头顶山体） foreach (IntVec3 cell in occupiedRect) { RoofDef roof = cell.GetRoof(parent.Map); if (roof != null && (roof.isThickRoof || roof == RoofDefOf.RoofRockThick)) { // 厚屋顶或岩顶视为完全遮挡 roofedCells++; } // 你也可以检查其他遮挡物，比如高大的建筑，但这需要更复杂的射线检测或区域查询 } // 计算遮挡率 roofCoverage = (float)roofedCells / totalCells; } } }

避坑点2：性能优化与Tick间隔。在UpdateRoofCoverage()方法中，我们遍历了建筑占据的所有格子。对于一个3x3的建筑，这是9个格子，每250 Tick检查一次，开销可以接受。但如果你的建筑很大（比如5x5），或者你在CompTick()中每帧都检查，性能就会急剧下降。务必根据实际情况调整CoverageCheckInterval。对于静态遮挡（如山脉），检查间隔甚至可以更长（如每2000 Tick）。

避坑点3：电网更新时机。注意在UpdateEfficiency()最后，我们手动设置了powerComp.PowerOutput。这是因为DesiredPowerOutput是一个属性，其值的变化不会自动通知电网组件。你必须显式地更新powerComp.PowerOutput，电网才会重新计算并分配电力。忘记这一步是导致“发电建筑显示有输出但电网没电”的常见原因。

4. XML定义与游戏内实体绑定

4.1 定义建筑ThingDef

C#代码定义了行为，但要在游戏里“造”出这个建筑，还需要XML定义。在Defs/ThingDefs/下创建Buildings_Power.xml。

<?xml version="1.0" encoding="utf-8"?> <Defs> <ThingDef ParentName="BuildingBase"> <defName>SolarGeneratorCustom</defName> <label>自定义太阳能板</label> <description>一种先进的光伏板，能更高效地将阳光转化为电能。其输出随昼夜和天气动态变化，并受遮挡影响。</description> <graphicData> <texPath>Buildings/SolarGenerator</texPath> <!-- 指向Textures/Buildings/SolarGenerator.png --> <graphicClass>Graphic_Single</graphicClass> <drawSize>(3,3)</drawSize> <!-- 假设是3x3的建筑 --> </graphicData> <thingClass>Building</thingClass> <category>Building</category> <tickerType>Normal</tickerType> <!-- 使用Normal Tick，每帧更新 --> <size>(3,3)</size> <pathCost>14</pathCost> <statBases> <MaxHitPoints>150</MaxHitPoints> <Flammability>0.5</Flammability> <WorkToBuild>3000</WorkToBuild> <MarketValue>800</MarketValue> </statBases> <costList> <Steel>150</Steel> <Component>4</Component> <Glass>40</Glass> <!-- 自定义资源，需在OtherDefs中定义 --> </costList> <researchPrerequisites> <li>SolarPanels</li> <!-- 需要先研究原版“太阳能板”科技 --> </researchPrerequisites> <!-- 电力相关组件 --> <comps> <!-- 1. 电力生产者组件，链接到我们的C#类 --> <li Class="MySolarGeneratorMod.CompPowerPlantSolar"> <compClass>MySolarGeneratorMod.CompPowerPlantSolar</compClass> <basePowerConsumption>0</basePowerConsumption> <!-- 注意：这里不直接设置basePowerConsumption，因为输出是动态的，由C#代码控制 --> </li> <!-- 2. 可开关组件（Flickable） --> <li Class="CompFlickable"/> <!-- 3. 可拆解组件（如果需要） --> <li Class="CompProperties_Self拆解"> <workTo拆解Factor>0.5</workTo拆解Factor> </li> </comps> <!-- 放置规则：需要开阔空间，不能被屋顶覆盖 --> <placementRules> <li>PlacementHelper_NoRoof</li> </placementRules> <designationCategory>Power</designationCategory> <inspectorTabs> <li>ITab_Power</li> <!-- 在电力标签页显示 --> </inspectorTabs> </ThingDef> </Defs>

避坑点4：compClass与Class属性。在<comps>列表中，Class属性指向的是组件属性类（CompProperties）的完整命名空间和类名，而compClass是CompProperties内部的一个字段，指向实际的组件逻辑类（CompPowerPlantSolar）。有时你会看到只使用Class属性，并在C#的CompProperties派生类中指定compClass。上述写法是一种清晰且常见的混合写法，确保XML能正确找到你的C#逻辑。

4.2 添加自定义Gizmo（命令工具）

为了让玩家直观地看到当前发电效率和遮挡情况，我们需要添加一个自定义的Gizmo。这需要在我们的CompPowerPlantSolar类中重写CompGetGizmosExtra方法。

using System.Collections.Generic; using RimWorld; using UnityEngine; using Verse; namespace MySolarGeneratorMod { public class CompPowerPlantSolar : CompPowerPlant { // ... 之前的代码 ... // 重写此方法以添加自定义Gizmo public override IEnumerable<Gizmo> CompGetGizmosExtra() { // 首先返回基类的Gizmo（如开关按钮） foreach (Gizmo gizmo in base.CompGetGizmosExtra()) { yield return gizmo; } // 添加我们自定义的信息显示Gizmo yield return new Command_Action { defaultLabel = "太阳能板状态", defaultDesc = $"当前发电效率: {curEfficiency:P1}\n遮挡率: {roofCoverage:P1}\n输出功率: {DesiredPowerOutput:F0} W", icon = ContentFinder<Texture2D>.Get("UI/Commands/SolarInfo"), // 需要准备一个图标 action = delegate { // 点击后可以显示更详细的信息，这里简单打个日志 Log.Message($"太阳能板状态详情 - 位置: {parent.Position}, 效率: {curEfficiency:P1}"); }, // 禁用点击效果，仅作为信息显示 Disabled = true, // 即使禁用也显示，并自定义禁用时的颜色和提示 disabledReason = "此为状态显示器", }; } } }

避坑点5：Gizmo的性能与生成频率。CompGetGizmosExtra在玩家选中建筑时会被频繁调用。确保其中的逻辑轻量，不要进行复杂的计算或数据库查询。所有动态数据（如curEfficiency）都应该在CompTick或类似更新循环中预先计算好，Gizmo只负责读取和显示。

5. 纹理制作、本地化与测试

5.1 创建与导入纹理

游戏中的建筑需要视觉表现。你需要为你的太阳能板制作纹理图片。基本要求：

• 格式：PNG或DDS，支持透明通道。
• 尺寸：必须是2的幂次方（如 256x256, 512x512）。对于3x3格的建筑，游戏会将其平铺显示，因此你的纹理应该设计成能无缝衔接的样式。
• 路径：按照项目结构，将最终图片（例如SolarGenerator.png）放入Textures/Buildings/目录下。
• 制作技巧：可以参考原版游戏的纹理（位于RimWorld\Mods\Core\Textures\Things\Building\Power），使用像Aseprite、Photoshop或免费的GIMP等工具进行绘制。保持与原版一致的美术风格（低多边形、略带手绘感）会让你的Mod更协调。

5.2 实现多语言本地化

为了让Mod支持中文等其他语言，需要在Languages/ChineseSimplified/Keyed/Strings.xml中添加翻译：

<?xml version="1.0" encoding="utf-8"?> <LanguageData> <!-- ThingDefs --> <SolarGeneratorCustom.label>自定义太阳能板</SolarGeneratorCustom.label> <SolarGeneratorCustom.description>一种先进的光伏板，能更高效地将阳光转化为电能。其输出随昼夜和天气动态变化，并受遮挡影响。</SolarGeneratorCustom.description> <!-- Gizmo 和 UI 文本 --> <MySolarGeneratorMod.SolarGenerator.StatusGizmoLabel>太阳能板状态</MySolarGeneratorMod.SolarGenerator.StatusGizmoLabel> <MySolarGeneratorMod.SolarGenerator.EfficiencyTip>效率：{0}</MySolarGeneratorMod.SolarGenerator.EfficiencyTip> <!-- 研究项目（如果添加了新的） --> <ResearchProject_SolarGeneratorCustom.label>高级光伏技术</ResearchProject_SolarGeneratorCustom.label> </LanguageData>

在C#代码中，使用Keyed翻译而不是硬编码字符串：

// 不好的做法： defaultLabel = "太阳能板状态"; // 好的做法： defaultLabel = "MySolarGeneratorMod.SolarGenerator.StatusGizmoLabel".Translate();

避坑点6：翻译键（Key）的命名空间。为了避免与其它Mod冲突，翻译键最好以你的Mod的包ID或一个独特前缀开头，如MySolarGeneratorMod.。

5.3 在游戏中测试与调试

1. 编译与部署：在Visual Studio中编译项目为Release模式，将生成的MySolarGeneratorMod.dll复制到Mod目录的Assemblies/文件夹下。
2. 激活Mod：启动RimWorld，在Mod配置界面激活你的Mod。确保加载顺序正确，如果依赖HugsLib等库，需将其放在你的Mod之前加载。
3. 使用开发模式：在游戏设置中开启“开发模式”。这将允许你：
   • 即时建造：按Ctrl+F12打开开发者工具，使用“Spawn”菜单直接放置你的太阳能板。
   • 查看调试信息：选中建筑，观察自定义Gizmo是否正常显示，信息是否正确。
   • 测试逻辑：使用“时间控制”加速游戏，观察昼夜交替时发电量的平滑变化。用开发工具放置屋顶，测试遮挡检测是否生效。
4. 日志排查：所有Log.Message、Log.Warning、Log.Error的输出都可以在游戏目录的Player.log文件中找到（或在开发模式控制台查看）。这是排查空引用异常（NullReferenceException）、逻辑错误的最重要工具。

避坑点7：版本兼容性与热重载。RimWorld版本更新（如从1.3到1.4）可能会修改API，导致Mod失效。在About.xml中准确声明supportedVersions。在开发过程中，修改C#代码后，需要重启游戏才能生效。修改XML或纹理文件有时可以通过游戏内的“重新加载所有Mod”功能（开发模式）生效，但并非总是可靠，重启是最稳妥的方式。

6. 进阶优化与功能扩展

6.1 性能深度优化

我们的基础实现已经考虑了Tick间隔，但还有优化空间：

• 按需更新：只有当太阳能板在屏幕上或附近有活动时，才进行高频率的更新（如每Tick计算昼夜效率）。当它远离玩家视野时，可以大幅降低更新频率（如每1000 Tick一次）。这可以通过重写CompTickRare（每250 Tick调用）和CompTickLong（每2000 Tick调用）来实现，并根据与玩家摄像机的距离动态切换。
• 遮挡计算优化：UpdateRoofCoverage中的遍历对于大型建筑或大量建筑仍是负担。可以考虑：
  • 使用Map.areaManager.Home或自定义区域来标记“需要检查遮挡”的区域，只在区域变化时重新计算。
  • 将遮挡率计算分摊到多帧完成，每帧只计算一部分格子。
  • 对于静态遮挡（山脉），在建筑放置时计算一次并缓存，除非周围地形被改变（如挖掘、坍塌）。

6.2 添加可研究升级

让太阳能板可以通过研究解锁升级功能，例如：

1. 储能涂层：研究后，太阳能板在白天效率略降，但能在夜间提供少量基础电力（如最大输出的10%）。
2. 自动清洁系统：减少沙尘暴、火山灰对发电效率的影响。
3. 双轴追踪：通过研究使太阳能板能缓慢追踪太阳，提升白天的平均发电效率。

实现方式：在CompPowerPlantSolar中添加代表升级状态的布尔标志或等级变量。在CalculateDayNightEfficiency方法中，根据这些标志调整计算逻辑。同时，需要创建对应的ResearchProjectDefXML定义，并在研究完成后，通过游戏事件或Hediff（增益效果）系统将升级应用到已建造的建筑上（这涉及更复杂的保存/加载逻辑）。

6.3 实现更精确的阴影投射与可视化

原版太阳能板只检查屋顶。我们可以实现更真实的阴影系统：

• 动态阴影检测：使用GenSight.LineOfSight或射线投射（ShotReport.HitReportFor）来检测在太阳方向（随时间变化）上是否有高山、城墙或其他高大建筑遮挡。
• 可视化反馈：在建筑上或地面上绘制一个动态的“阴影区域”，让玩家直观地看到哪些物体会造成遮挡。这需要重写Draw或Print方法，在图形层上叠加绘制。

这部分代码较为复杂，需要深入理解RimWorld的绘制管线。一个简单的起点是，在Gizmo中不仅显示数字，还用一个从绿色（无遮挡）到红色（完全遮挡）的颜色条来直观表示遮挡状态。

7. 完整源码结构与关键文件回顾

以下是本指南所涉及的核心文件及其作用，你可以据此组织你的项目：

• Source/CompPowerPlantSolar.cs：核心逻辑组件，负责动态发电计算、遮挡检测和Gizmo显示。
• Defs/ThingDefs/Buildings_Power.xml：定义建筑在游戏内的所有静态属性，如成本、尺寸、贴图路径和挂载的组件。
• Defs/ResearchProjectDefs/Research_Solar.xml：（可选）定义解锁升级科技的研究项目。
• About/About.xml：Mod的元数据，决定Mod是否能在游戏中显示和加载。
• Languages/ChineseSimplified/Keyed/Strings.xml：提供中文翻译，提升Mod的友好度。
• Textures/Buildings/SolarGenerator.png：建筑的视觉纹理。

将C#项目编译后的MySolarGeneratorMod.dll放入Assemblies/，把上述XML和纹理文件放到对应目录，一个功能完整的太阳能发电机Mod就打包完成了。你可以将其压缩成.zip文件（注意保持目录结构），改后缀为.rimmod，即可分享给其他玩家或上传至创意工坊。

开发Mod最大的成就感，莫过于看到自己写的代码在喜爱的游戏世界里真正运行起来，并创造出新的玩法。从复刻一个太阳能板开始，你已经掌握了定义物品、编写游戏逻辑、处理玩家交互的基本流程。接下来，你可以尝试修改更多参数，比如让它在极昼环境下超频发电，或者与天气控制Mod联动，在晴天时额外加成。记住，多查阅RimWorld官方未公开但通过反编译或社区文档（如RimWorld Wiki, Harmony库文档）可了解的类库，多利用开发模式进行实时调试，遇到问题先查日志，大部分难题都能在社区找到答案。