ONI Agent Bridge - initial mod implementation

2026-05-30 11:00:36 +08:00
commit 1f25d3d879
95 changed files with 50686 additions and 0 deletions
--- a/ONIModTutorial/ONIModTutorial-main/harmony-reference.md
+++ b/ONIModTutorial/ONIModTutorial-main/harmony-reference.md
@ -0,0 +1,395 @@
+---
+sidebar: false
+---
+<a href="javascript:history.back()" class="back-button">
+  ⬅ 返回
+</a>
+
+<style scoped>
+.back-button {
+  position: fixed;
+  left: 20px;
+  top: 100px;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 10px 15px;
+  background-color: var(--vp-c-brand); 
+  color: white !important;
+  border-radius: 20px;
+  text-decoration: none !important;
+  font-weight: bold;
+  box-shadow: 0 4px 12px rgba(0,0,0,0.1);
+  transition: transform 0.2s;
+  z-index: 100;
+  cursor: pointer;
+}
+
+.back-button:hover {
+  transform: scale(1.05);
+  opacity: 0.9;
+}
+</style>
+
+
+# 🧩 Harmony 补丁整理
+
+> **本篇是 Harmony 在《缺氧（ONI）》Mod 开发中的实战速查表**  
+> 👉 目标：**快速了解以及什么时候该用哪一种 Patch**
+
+---
+
+## 📖 阅读指引
+
+- **基础操作**：了解 `Harmony` 初始化及 `Prefix / Postfix` 的基本用法。
+- **常用参数**：了解 `__instance / __state / AccessTools` 读写游戏数据。
+- **特殊场景**：了解 `Transpiler / Finalizer` 处理底层逻辑与异常的方式。
+
+---
+
+## 🧠 一、Harmony 是什么？
+
+Harmony 是一个 **运行时方法注入库**，用于在**不修改源代码**的情况下：
+
+- 插入逻辑
+- 拦截原方法
+- 修改返回值
+- 重写部分执行流程
+
+---
+
+## 🧩 二、Patch 类型总览
+
+| Patch 类型 | 执行时机 | 常见用途 |
+|----------|----------|----------|
+| Prefix | 原方法执行前 | 拦截 / 改参数 / 阻止执行 |
+| Postfix | 原方法执行后 | 补充逻辑 / 改返回值 |
+| Transpiler | IL 层 | 改硬编码 / if / 常量 |
+| Finalizer | 所有逻辑后 | 捕获异常 / 兜底 |
+---
+
+## ⚙️ 三、Harmony 初始化
+
+> 在 ONI 中，继承 UserMod2 后，游戏会自动帮你执行 harmony.PatchAll()。你不需要再手动调用它，除非你有特殊的动态补丁需求。
+
+
+```csharp
+using HarmonyLib;
+using KMod;
+
+namespace MyMod
+{
+    public class MyFirstMod : UserMod2
+    {
+        public override void OnLoad(Harmony harmony)
+        {
+            // 1. 必须保留基类调用，它会处理自动 PatchAll
+            base.OnLoad(harmony);
+
+            // 2. 这里通常用来放“全局初始化”逻辑
+            // 比如：打印日志确认 Mod 已加载
+            Debug.Log("MyFirstMod 已成功加载！");
+        }
+    }
+}
+```
+
+---
+
+## 🟦 四、Prefix（执行前拦截）
+
+`Prefix` 用于在原代码跑起来之前先一步执行。
+
+### 4.1 基础用法：单纯插入逻辑
+如果你只想在某个动作发生时顺便做点事（比如记录日志），补丁返回 void 即可。
+
+```csharp
+[HarmonyPatch(typeof(Operational), nameof(Operational.SetActive))]
+public static class Log_Patch
+{
+    public static void Prefix(bool value)
+    {
+        // 只是看一眼参数，不影响原逻辑执行
+        Debug.Log($"建筑状态尝试切换为: {value}");
+    }
+}
+```
+
+---
+### 4.2 进阶用法：干预原逻辑
+
+如果你想改变游戏的结果，需要注意 bool 返回值和 ref 关键字的作用。
+
+| 方式 | 代码关键点| 实际效果 |
+|----------|----------|----------|
+| 强行篡改 | `ref bool value` | 改指令。 原代码照样跑，但你偷偷换掉了它的参数（比如让关机指令变成开机） |
+| 彻底拦截 | `return false` | 断后路。 原代码被直接掐断，后面的逻辑（动画、音效、状态改变）全都不再执行 |
+
+
+**案例对比：**
+我们依然是在`[HarmonyPatch(typeof(Operational), nameof(Operational.SetActive))]`上打补丁。
+```csharp
+
+// 情况 A：篡改参数（原逻辑继续跑，但用你的数）
+public static void Prefix(ref bool value) 
+{
+    value = true; // 哪怕玩家点了关闭，建筑也会因为参数被改而保持开启
+}
+
+// 情况 B：彻底拦截（原逻辑直接罢工）
+public static bool Prefix(bool value, bool force_ignore)
+{
+    return false;  // 原方法体内的代码一行都不会跑，功能被完全“冻结”
+}
+
+```
+
+---
+<h2 id="postfix">🟩 五、Postfix（执行后补充）</h2>
+
+`Prefix` 在原方法执行完毕后运行。它是最推荐的补丁方式，因为它不会中断游戏的正常逻辑，兼容性最好。
+
+### 5.1 实战代码：追加额外逻辑
+- 作用： 在原逻辑跑完后，顺便执行一些你自己的操作。
+
+```csharp
+[HarmonyPatch(typeof(ElectrolyzerConfig), "CreateBuildingDef")]
+public class ElectrolyzerCreateBuildingDef_Patch
+{
+    public static void Postfix(ref BuildingDef __result)
+    {
+        // 将电解器的功耗改为 1 瓦
+        __result.EnergyConsumptionWhenActive = 1f;
+        Debug.Log("电解器的功耗已被修改为 1 瓦");
+    }
+}
+```
+- 场景： 初始化后的属性修正、添加自定义的组件、触发额外的通知。
+- 优势： 无论你的代码写得好不好，原版代码都已经安全跑完了，不会导致核心功能丢失。
+
+---
+### 5.2 修改返回值：修改计算结果
+
+- 作用： 劫持原方法的返回值，让游戏拿到你“调包”后的结果。
+```csharp
+[HarmonyPatch(typeof(Overheatable), nameof(Overheatable.OverheatTemperature), MethodType.Getter)]
+public static class Overheatable_OverheatTemperature_Patch
+{
+    // ref __result 指向原方法算出来的那个返回值
+    public static void Postfix(ref float __result)
+    {
+        __result = 9999f; // 让建筑永远不会因为温度过高而损坏（强行改掉判定数值）
+    }
+}
+
+```
+
+| 枚举项 | 怎么认出它（看 ILSpy/dnSpy） | 干嘛的 |
+| :--- | :--- | :--- |
+| **Normal** | 方法名后面带个括号，比如 OnSpawn() | 在某个动作执行前后“插一脚” |
+| **Getter** | 代码里长这样：float Speed { get; } | 用于修改游戏“读取”到的数据 |
+| **Setter** | 代码里长这样：set { ... } | 用于在游戏尝试修改某个数值时进行拦截 |
+| **Constructor** | 跟类名长得一模一样的方法 | 在对象刚创建、还没放进世界时，提前修改它的默认字段或初始化逻辑 |
+| **StaticConstructor** |前面带 static 的构造函数 | 专门用来修改游戏加载时就定死的全局静态常量 |
+| **Enumerator** | 里面有一堆 yield return 的方法 | 专门对付 ONI 里的异步动作、动画序列或那些不是瞬间完成的任务 |
+
+
+
+<h3 id="postfix-Overloading">5.3 处理重载</h3>
+在 ONI 源码中，经常会出现多个方法名相同但参数不同的方法。如果不指定参数类型，Harmony 会报错。
+
+**案例：拦截 `ModUtil.AddBuildingToPlanScreen`**
+这个方法在游戏源码中有多个重载版本，我们对比来看：
+
+```csharp
+public static class ModUtil
+{
+    // 重载 A：只有 2 个参数
+    public static void AddBuildingToPlanScreen(HashedString category, string building_id) { ... }
+
+    // 重载 B：有 3 个参数
+    public static void AddBuildingToPlanScreen(HashedString category, string building_id, string subcategoryID) { ... }
+
+    // 重载 c：有 5 个参数
+    public static void AddBuildingToPlanScreen(HashedString category, string building_id, string subcategoryID, string relativeBuildingId, ModUtil.BuildingOrdering ordering = ModUtil.BuildingOrdering.After) { ... }
+}
+
+// 【对应的 HarmonyPatch 写法】
+// 拦截“重载 B”，必须明确写出那 3 个参数的类型：
+[HarmonyPatch(typeof(ModUtil), "AddBuildingToPlanScreen", new Type[] { typeof(HashedString), typeof(string), typeof(string) })]
+// 试试举一反三 重载a会是怎么样的？
+
+// ❌ 错误写法
+[HarmonyPatch(typeof(ModUtil), "AddBuildingToPlanScreen")]
+
+```
+
+---
+
+### 🛠️ 总结：Prefix 与 Postfix 怎么选？
+- 选 Prefix 的唯一理由：你需要在事情发生之前拦住它（比如阻止一个动作，或者在原逻辑使用参数前改掉参数）。
+
+- 其他情况全选 Postfix：只要不需要拦截原逻辑，就往原逻辑后面接代码。这是保持 Mod 稳定、不坏档的金法则。
+
+---
+
+
+
+## 🔁 六、状态桥接（__state 传值）
+有时候你需要在执行之后知道执行之前发生了什么（比如：存货前有多少，存货后剩多少）。`__state` 就是专门用来在 `Prefix` 和 `Postfix` 之间带货的“临时储物柜”。
+
+
+### 6.1 实战用法：前后状态对比
+- 作用： 记录一个初始值，等原逻辑跑完后再拿出来算差值。
+```csharp
+[HarmonyPatch(typeof(Storage), "Store")]
+public static class Storage_Monitor_Patch
+{
+    // 1. 在执行前，把当前帧数塞进 __state 储物柜
+    public static void Prefix(out int __state)
+    {
+        __state = Time.frameCount;
+    }
+
+    // 2. 在执行后，从 __state 储物柜拿出刚才存的帧数
+    public static void Postfix(int __state)
+    {
+        int cost = Time.frameCount - __state;
+        if (cost > 0) 
+        {
+            Debug.Log($"这次存货居然花了 {cost} 帧的时间！");
+        }
+    }
+}
+```
+### 💡 为什么用它？
+
+* **性能追踪：** 记录方法运行前后的时间差。
+* **逻辑判定：** 记录执行前的数值（比如生命值），执行后发现数值没变，就触发补救逻辑。
+* **简洁性：** 它只在这一次补丁调用中有效，跑完就销毁，不会像全局变量那样污染你的代码。
+
+### 🔑 参数细节说明（避坑）
+
+* **Prefix 里：** 必须用 out 或者 ref（比如 out int __state），否则存不进去。
+* **Postfix 里：** 直接用（比如 int __state）即可拿到之前存的值。
+
+
+---
+
+## 🔓 七、访问 private 字段（AccessTools与 ___）
+在 ONI 源码中，很多变量被声明为 `private` 你直接用 `__instance` 变量名 是访问不到的。这时有两种常用的“破门”方法。
+
+
+### 7.1 方法一：三下划线暗号（最快、最推荐）
+如果只是想简单读写一个实例变量，Harmony 提供了一个极简写法：在参数名前加 三个下划线。
+```csharp
+[HarmonyPatch(typeof(Storage), "OnSpawn")]
+public static class Storage_Easy_Patch
+{
+    // ___capacityKg 对应 Storage 类里的私有变量 capacityKg
+    public static void Postfix(Storage __instance, ref float ___capacityKg)
+    {
+        ___capacityKg = 9999f; // 直接像改普通变量一样改掉它
+    }
+}
+```
+### 7.2 方法二：使用 AccessTools（性能更好、更强大）
+当你需要在多个地方频繁访问同一个变量，或者要处理 `static`（静态）私有变量时，建议先提前定义一个“后门”。
+```csharp
+using System.Reflection;
+
+public static class Storage_Hard_Patch
+{
+    // 1. 先定义后门（只找一次，性能更优）
+    private static readonly FieldInfo CapacityField = 
+        AccessTools.Field(typeof(Storage), "capacityKg");
+
+    [HarmonyPatch(typeof(Storage), "OnSpawn")]
+    public static class Patch
+    {
+        public static void Postfix(Storage __instance)
+        {
+            // 2. 暴力写入新值
+            CapacityField.SetValue(__instance, 9999f);
+        }
+    }
+}
+```
+
+### 💡 怎么选？
+
+* **三下划线 (`___`)**：**日常主力。** 只要能跑通，就优先用它，代码短且不容易写错。
+* **AccessTools**：**重型工具。** 
+  - 专门对付 `static private`（静态私有）变量。
+  - 适合在补丁函数体外面拿取数据。
+  - 如果你需要极致的性能优化，提前定义一个 `static readonly FieldInfo` 会比三下划线快那么一点点。
+---
+
+## 🧬 Transpiler（改底层指令）
+这是 Harmony 中最硬核的补丁。
+- 它不是在方法前后插话，而是直接冲进原代码内部，把某几行代码“抠掉”或者“掉包”。
+
+### 8.1 它的作用
+如果你发现 `Prefix` 和 `Postfix` 都没法改掉某个逻辑，通常是因为那个逻辑是硬编码在方法中间的。
+
+* **改常量：**  比如代码里写死了一个 `if (speed > 10f)`，你想把 `10f` 改成 `100f`。
+* **删代码：** 比如你想把原版中某一行烦人的检测逻辑彻底抹除。
+* **加指令：** 在方法的第 50 行和第 51 行中间塞进你自己的逻辑。
+
+### 8.2 实战代码：修改硬编码数值
+- 场景： 游戏原本规定挖矿只掉一半掉落物`0.5f`，我们通过补丁把它改成全掉 `1.0f`。
+```csharp
+[HarmonyPatch(typeof(WorldDamage), "OnDigComplete")]
+public static class WorldDamage_OnDigComplete_Patch
+{
+    // Transpiler 接收的是一组 IL 指令集
+    private static IEnumerable<CodeInstruction> Transpiler(IEnumerable<CodeInstruction> instructions)
+    {
+        foreach (var ins in instructions)
+        {
+            // 目标：找到指令是“加载浮点数 0.5”的那一行
+            if (ins.opcode == OpCodes.Ldc_R4 && (float)ins.operand == 0.5f)
+            {
+                // 改成 1.0f
+                ins.operand = 1.0f;
+            }
+            yield return ins;
+        }
+    }
+}
+```
+### ⚠️ 为什么说要慎用？
+* **报错难找：** 普通的补丁写错，通常只是功能失效；`Transpiler` 写错，可能会导致游戏直接闪退或整个类崩掉。
+* **极易冲突：** 如果有两个 Mod 同时对同一个方法的同一行代码动了“手术”，游戏大概率会当场报废。
+* **门槛高：** 你需要看懂 IL（中间语言） 指令（类似于 `ldarg.0`  `call`  `stfld` 等），就像在看天书。
+
+---
+
+## 🧯 九、Finalizer（异常兜底）
+
+```csharp
+[HarmonyPatch(typeof(SomeClass), "SomeMethod")]
+public static class SomeMethod_Finalizer
+{
+    public static void Finalizer(Exception __exception)
+    {
+        if (__exception != null)
+        {
+            Debug.LogError(__exception);
+        }
+    }
+}
+```
+
+---
+
+## ⚠️ 十、ONI Mod 常见翻车点
+
+- Patch 方法忘记 `static`
+- 参数签名与原方法不一致
+- Prefix `return false` 但没处理返回值
+- Transpiler 修改逻辑过多
+
+
+---
+