新增建筑文档，详细说明建筑配置、存储和电力设置等内容

Author: ChiYuKe

content/buildings.md

@@ -0,0 +1,196 @@
+# 新增建筑
+
+这一章做一个真正会出现在建造菜单里的建筑。建筑和普通物品不一样，它要处理占格、材料、建造时间、电力、端口、储存、逻辑信号等内容，所以代码通常会拆成两部分：
+
+- `IBuildingConfig`：告诉游戏这个建筑长什么样、占几格、需要什么材料。
+- Harmony Patch：把建筑放进建造菜单，并解锁到某个科技里。
+
+下面的写法参考了 `NOIMods/AutomaticHarvest`，但会删掉自动收获器自己的业务逻辑，只保留新增建筑最常用的骨架。
+
+## 文件结构
+
+```text
+MyFirstBuilding/
+├── MyFirstBuildingConfig.cs
+├── Patches.cs
+└── STRINGS.cs
+```
+
+`MyFirstBuildingConfig.cs` 管建筑本体，`Patches.cs` 负责注册入口，`STRINGS.cs` 放名称和描述。
+
+## 建筑配置
+
+新增建筑需要继承 `IBuildingConfig`。最少要实现三个阶段：
+
+- `CreateBuildingDef()`：定义尺寸、动画、材料、建造规则。
+- `ConfigureBuildingTemplate()`：给建筑预制体加组件。
+- `DoPostConfigureComplete()`：在建筑完成配置后补运行组件。
+
+```csharp
+using TUNING;
+using UnityEngine;
+
+namespace MyFirstBuilding
+{
+    public class MyFirstBuildingConfig : IBuildingConfig
+    {
+        public const string ID = "MyFirstBuilding";
+
+        public override BuildingDef CreateBuildingDef()
+        {
+            BuildingDef def = BuildingTemplates.CreateBuildingDef(
+                ID,
+                1,
+                1,
+                "my_first_building_kanim",
+                30,
+                60f,
+                BUILDINGS.CONSTRUCTION_MASS_KG.TIER2,
+                MATERIALS.REFINED_METALS,
+                1600f,
+                BuildLocationRule.OnFloor,
+                DECOR.NONE,
+                NOISE_POLLUTION.NONE
+            );
+
+            def.Floodable = false;
+            def.Entombable = true;
+            def.Overheatable = false;
+            def.AudioCategory = "Metal";
+            def.DefaultAnimState = "off";
+            def.ObjectLayer = ObjectLayer.Building;
+
+            return def;
+        }
+
+        public override void ConfigureBuildingTemplate(GameObject go, Tag prefabTag)
+        {
+            go.AddOrGet<Operational>();
+            go.AddOrGet<CopyBuildingSettings>();
+        }
+
+        public override void DoPostConfigureComplete(GameObject go)
+        {
+            go.AddOrGet<LogicOperationalController>();
+        }
+    }
+}
+```
+
+先不要急着往里面塞功能。建筑能被注册、能建出来、能正常保存读取以后，再加自己的组件会稳很多。
+
+## 加储存
+
+如果建筑需要存东西，直接加 `Storage`：
+
+```csharp
+public override void ConfigureBuildingTemplate(GameObject go, Tag prefabTag)
+{
+    Storage storage = go.AddOrGet<Storage>();
+    storage.capacityKg = 1000f;
+    storage.storageFilters = STORAGEFILTERS.SOLIDS;
+    storage.showCapacityStatusItem = true;
+    storage.showCapacityAsMainStatus = true;
+
+    storage.SetDefaultStoredItemModifiers(new[]
+    {
+        Storage.StoredItemModifier.Preserve
+    });
+}
+```
+
+`capacityKg` 是容量，`storageFilters` 是允许放入的标签。比如只收种子可以用 `GameTags.Seed`，只收食物可以用 `GameTags.Edible`。
+
+## 加电力
+
+建筑需要耗电时，在 `CreateBuildingDef()` 里打开电力输入：
+
+```csharp
+def.RequiresPowerInput = true;
+def.EnergyConsumptionWhenActive = 120f;
+def.SelfHeatKilowattsWhenActive = 1f;
+def.PowerInputOffset = new CellOffset(0, 0);
+```
+
+然后在 `DoPostConfigureComplete()` 里补 `EnergyConsumer`：
+
+```csharp
+public override void DoPostConfigureComplete(GameObject go)
+{
+    go.AddOrGet<Operational>();
+    go.AddOrGet<EnergyConsumer>();
+}
+```
+
+如果忘了 `EnergyConsumer`，建筑可能显示有电力口，但运行状态不对。
+
+## 放进建造菜单
+
+建筑配置写好以后，还需要告诉游戏：把它放到哪个分类里。
+
+```csharp
+using HarmonyLib;
+
+namespace MyFirstBuilding
+{
+    public static class Patches
+    {
+        [HarmonyPatch(typeof(GeneratedBuildings), "LoadGeneratedBuildings")]
+        public static class GeneratedBuildings_LoadGeneratedBuildings_Patch
+        {
+            public static void Prefix()
+            {
+                ModUtil.AddBuildingToPlanScreen("Base", MyFirstBuildingConfig.ID);
+            }
+        }
+
+        [HarmonyPatch(typeof(Db), "Initialize")]
+        public static class Db_Initialize_Patch
+        {
+            public static void Postfix()
+            {
+                Db.Get().Techs.Get("BasicRefinement")
+                    .unlockedItemIDs
+                    .Add(MyFirstBuildingConfig.ID);
+            }
+        }
+    }
+}
+```
+
+`"Base"` 是建造菜单分类，`"BasicRefinement"` 是科技 ID。想放到别的分类或科技里，可以先找一个原版建筑，看看它所在的分类和解锁科技，再照着填。
+
+## 本地化文本
+
+建筑菜单需要名称、描述和效果：
+
+```csharp
+namespace MyFirstBuilding
+{
+    public static class STRINGS
+    {
+        public static class BUILDINGS
+        {
+            public static class PREFABS
+            {
+                public static class MYFIRSTBUILDING
+                {
+                    public static LocString NAME = "我的第一个建筑";
+                    public static LocString DESC = "一个用于测试建筑注册流程的小建筑。";
+                    public static LocString EFFECT = "可以建造、选择，并接入后续自定义逻辑。";
+                }
+            }
+        }
+    }
+}
+```
+
+注意类名通常使用大写 ID。也就是说 `MyFirstBuildingConfig.ID = "MyFirstBuilding"` 时，文本路径一般是 `STRINGS.BUILDINGS.PREFABS.MYFIRSTBUILDING`。
+
+## 常见问题
+
+建筑出现在菜单但不能建，多半是材料分类或科技解锁写错了。先把材料改成 `MATERIALS.ALL_METALS` 或 `MATERIALS.RAW_MINERALS` 测试。
+
+建筑建出来后状态很怪，检查 `Operational`、`EnergyConsumer`、`Storage` 这些组件是不是放在了正确阶段。
+
+动画不显示，先确认 `.anim`、`.build`、`.png` 都打进 `anim/assets`，并且 `Assets.GetAnim()` 使用的是 `xxx_kanim`。