C# DLL Mod(仅 PC)C# DLL mods (PC only)

把编译好的程序集放进 Mod,游戏在启动时加载它并调用你的入口类。能力最完整,但只能在 PC 上运行;手机会提示并跳过整个 Mod。 Ship a compiled assembly; the game loads it at startup and calls your entry class. The most capable option, but PC only — mobile shows a notice and skips the whole mod.

清单与目录Manifest and layout

<ModMetaVersion>
  <version>v_common</version>
  <lib>0Harmony.dll</lib>           <!-- 可选,可重复,先于 main 加载optional, repeatable, loaded before main -->
  <main>MyMod.dll</main>            <!-- 只使用第一个only the first is used -->
</ModMetaVersion>
MyMod/
├─ Manifest/manifest.xml
└─ v_common/
   ├─ Assemblies/MyMod.dll, 0Harmony.dll
   └─ Resources/...            ← 可同时带数据与资源← data and resources may be included
  • 内容完全相同(SHA-256 一致)的程序集只加载一次,后续重复的会被跳过。多个 Mod 带同一份库时互不冲突,但不要让两个 Mod 的 main 是同一个文件。Byte-identical assemblies (same SHA-256) load once; later duplicates are skipped. Sharing a library between mods is fine, but two mods must not use the same file as main.

入口类Entry class

主程序集中必须有一个无命名空间、名为 ModPluginLauncher、继承 BaseModLauncher 且带无参构造函数的公共类。游戏依次执行: The main assembly must contain a public class named ModPluginLauncher in the global namespace, deriving from BaseModLauncher, with a parameterless constructor. The game then:

  1. 创建实例,调用 setModMetaConfig(config)(之后可用 this.config)Creates the instance and calls setModMetaConfig(config) (then this.config is set)
  2. 调用 setDefLoader(new BaseModDefLoader(config)) 设置默认加载器Calls setDefLoader(new BaseModDefLoader(config)) with the default loader
  3. 调用你的 launcher()——配置表尚未加载Calls your launcher() — definitions are not loaded yet
  4. 配置表读入后调用 defLoader.initModDef()——在这里修改或新增数据After tables are read, calls defLoader.initModDef() — modify or add data here

要在第 4 步执行自己的逻辑,就在 launcher() 里换上自己的加载器:To run code at step 4, install your own loader from launcher():

MyMod.cs
using System;

public sealed class ModPluginLauncher : BaseModLauncher
{
    public override void launcher()
    {
        base.launcher();
        setDefLoader(new MyDefLoader(config));
    }
}

sealed class MyDefLoader : BaseModDefLoader
{
    public MyDefLoader(ModXmlManifest config) : base(config) { }

    // Rows are read but not yet initialised; use beans, not beansDict/getDataID.
    public override void initModDef()
    {
        T_FoodDef template = null;
        foreach (T_FoodDef row in T_FoodDef.beans)
            if (row.ID == "3") { template = row; break; }
        if (template == null)
            throw new InvalidOperationException("T_FoodDef ID=3 not found");

        template.Price *= 2;                                  // change a built-in row

        T_FoodDef added = T_FoodDef.getTemplateDef("3");      // deep copy
        added.ID = "dll_tomato";                              // becomes <packageId>_dll_tomato
        addRow(added);                                        // prefixes ID, records owner
    }
}
  • initModDef 在每次配置表加载时都会被调用。实际游戏中启动时只加载一次,但仍建议写成可重复执行(先查重再新增),参考 mods/hullmodpatch/Source/HullModTweak.cs。initModDef runs on every definition load. The shipped game loads once at startup, but keep it idempotent (check before adding), as in mods/hullmodpatch/Source/HullModTweak.cs.
  • 直接 new 出来的行只有代码默认值,Type 为 -1;请设置 Type(表的 Type ID)与需要的字段后再 addRow,或像上例一样用 getTemplateDef 复制原版行。Rows created with new only have code defaults and Type = -1; set Type (the table's Type ID) and the needed fields before addRow, or copy a built-in row with getTemplateDef as above.
  • 改写会影响缓存的字段(如船插效果文本)时,同时清除对应缓存,见 hullmodpatch 示例中的 RowUpdate。When changing fields that feed caches (e.g. hull-mod effect text), invalidate those caches too — see RowUpdate in the hullmodpatch example.

编译Building

  • 引用游戏目录 <游戏>_Data/Managed/ 下的 Assembly-CSharp.dll 与所需的 UnityEngine*.dll。Reference Assembly-CSharp.dll and the needed UnityEngine*.dll from <Game>_Data/Managed/.
  • 目标框架选 .NET Framework 4.x 或 .NET Standard 2.x(PC 版使用 Unity 的 Mono 运行时)。Target .NET Framework 4.x or .NET Standard 2.x (the PC build uses Unity's Mono runtime).
  • 只能使用公开(public)成员。例如 ModPluginManager 是 internal,Mod 无法直接访问;当前 Mod 的信息请用 config。Only public members are usable. ModPluginManager, for instance, is internal; use config for your own mod's information.
  • 游戏更新后需要重新编译并测试:DLL 直接绑定游戏代码,签名变化会导致加载或运行时错误。Rebuild and retest after every game update: DLLs bind directly to game code, and signature changes break loading or runtime.
  • 可参考的构建脚本:mods/hullmodpatch/Build.ps1(使用 Unity 自带编译器)。A working build script: mods/hullmodpatch/Build.ps1 (uses Unity's bundled compiler).

自定义建筑Custom buildings

ModDelegateDispatch 提供两个事件,让 Mod 接管建筑数据与建筑对象的创建。游戏按订阅顺序调用,第一个返回非 null 的结果生效;都返回 null 时使用默认逻辑。 ModDelegateDispatch exposes two events that let a mod take over creation of building data and building objects. Subscribers are called in order; the first non-null result wins, otherwise the default logic runs.

事件Event调用位置Called from返回Returns
generator_BuildBeanBuildGenerator,放置建筑生成数据时, when placing a buildingFWBuildBean
generator_BuildClassBuildGenerator,创建建筑对象时, when instantiating the building objectBaseBuild

示例:mods/Mod_BuildCustom(仓库内仅有编译产物)。Example: mods/Mod_BuildCustom (binary only in the repository).

使用 Harmony 打补丁Patching with Harmony

示例 mods/Mod_Harmony 展示了把 0Harmony.dll 作为 lib 加载、再由主程序集使用的结构(仓库内仅有编译产物)。补丁绕开了游戏的所有接口约定,版本更新后最容易失效,请只在没有其他办法时使用。DLL Mod 没有卸载回调,补丁会一直生效到游戏退出。 The mods/Mod_Harmony example shows the layout: 0Harmony.dll loaded as a lib and used from the main assembly (binary only in the repository). Patches bypass every contract and are the first thing to break on updates — use them only as a last resort. DLL mods have no unload callback, so patches stay active until the game exits.

运行时常用的游戏接口、线程注意事项,以及哪些事只能用 DLL 做,见常用游戏 API。For the game interfaces used most at runtime, threading notes and what only a DLL can do, see Common game APIs.