ONIModTutorial

Appearance

验证环境

本页已在游戏 Build 740622、.NET Standard 2.1、Mod API 2 下验证。

编写第一个 Mod：节能电解器 ​

这一章做一个很小的 Mod：把电解器的功耗从 120W 改成 1W。

例子故意选得简单，因为第一步最重要的不是功能多复杂，而是确认项目能编译、能被游戏加载、补丁确实生效。

一、准备工作 ​

在开始之前，先创建一个用于存放开发版 Mod 的目录：

  • 路径：%USERPROFILE%\Documents\Klei\OxygenNotIncluded\mods\
  • 操作：在这个目录下创建 Dev 文件夹。

二、安装项目模板 ​

本教程推荐直接使用项目模板。模板会生成：

  • Mod.cs：Mod 入口和一个最小 Harmony 补丁示例。
  • STRINGS.cs：本地化字符串入口。
  • mod.yaml / mod_info.yaml：Mod 元数据。
  • Debug 输出路径：%USERPROFILE%\Documents\Klei\OxygenNotIncluded\mods\Dev\<项目名>\

安装方法 ​

text
%USERPROFILE%\Documents\Visual Studio 2022\Templates\ProjectTemplates
点击展开查看 ProjectTemplates 目录结构
ProjectTemplates 目录结构

重启 Visual Studio 后，创建项目时搜索 ONI Mod。

点击展开查看预览图
项目模板预览

检查游戏引用路径

模板通过 GameManagedDir 属性引用游戏目录。可以在创建项目时传入本机的 Managed 目录，例如：

text
<你的游戏目录>\OxygenNotIncluded_Data\Managed

如果使用命令行构建，可以传入 -p:GameManagedDir="...\Managed"；也可以在 .csproj 或用户级 MSBuild 属性中设置它。不要把其他机器的 Steam 安装路径写进项目。

三、创建项目 ​

  1. 打开 Visual Studio。
  2. 选择 创建新项目，搜索 ONI Mod。
  3. 项目名称填 MyFirstMod。
  4. 创建完成后，确认项目中能看到 Mod.cs、STRINGS.cs、mod.yaml 和 mod_info.yaml。

四、确认游戏核心库 ​

模板已经添加了常用引用。展开 依赖项，应该能看到类似下面的程序集：

  • 0Harmony.dll
  • Assembly-CSharp.dll
  • Assembly-CSharp-firstpass.dll
  • UnityEngine.CoreModule.dll
  • UnityEngine.UI.dll
  • Unity.TextMeshPro.dll

如果 Mod.cs 里的 HarmonyLib、KMod、UnityEngine 仍然是红色，通常是 GameManagedDir 路径不对。改完 .csproj 后，右键项目选择 重新加载项目。

五、编写补丁代码 ​

进阶指引

想继续了解补丁写法，可以先看 Harmony 补丁整理。

示例工程中的补丁源码位于 examples/FirstMod/Mod.cs，页面直接导入该文件，避免教程代码与可编译项目分叉：

csharp
using HarmonyLib;
using KMod;
using UnityEngine;

namespace ONITutorial.FirstMod
{
    public sealed class Mod : UserMod2
    {
        public override void OnLoad(Harmony harmony)
        {
            base.OnLoad(harmony);
            Debug.Log("[ONITutorial.FirstMod] Loaded");
        }

        [HarmonyPatch(typeof(ElectrolyzerConfig), nameof(ElectrolyzerConfig.CreateBuildingDef))]
        private static class ElectrolyzerPatch
        {
            private static void Postfix(ref BuildingDef __result)
            {
                if (__result != null)
                    __result.EnergyConsumptionWhenActive = 1f;
            }
        }
    }
}

调试技巧 ​

如果 Mod 运行不正常，先看游戏日志：

text
%USERPROFILE%\AppData\LocalLow\Klei\Oxygen Not Included\player.log

六、编译与部署 ​

  1. 点击顶部菜单栏的 生成 (Build) -> 生成解决方案，或者右键项目选择 生成 (Build)。
  2. 模板会把 Debug 构建结果直接输出到：
text
%USERPROFILE%\Documents\Klei\OxygenNotIncluded\mods\Dev\MyFirstMod\
  1. 确认这个目录里有 MyFirstMod.dll、mod.yaml 和 mod_info.yaml。
  2. 启动游戏，在 Mod 列表里启用 MyFirstMod。