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 asmain.
入口类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:
- 创建实例,调用
setModMetaConfig(config)(之后可用this.config)Creates the instance and callssetModMetaConfig(config)(thenthis.configis set) - 调用
setDefLoader(new BaseModDefLoader(config))设置默认加载器CallssetDefLoader(new BaseModDefLoader(config))with the default loader - 调用你的
launcher()——配置表尚未加载Calls yourlauncher()— definitions are not loaded yet - 配置表读入后调用
defLoader.initModDef()——在这里修改或新增数据After tables are read, callsdefLoader.initModDef()— modify or add data here
要在第 4 步执行自己的逻辑,就在 launcher() 里换上自己的加载器:To run code at step 4, install your own loader from launcher():
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。initModDefruns on every definition load. The shipped game loads once at startup, but keep it idempotent (check before adding), as inmods/hullmodpatch/Source/HullModTweak.cs.- 直接
new出来的行只有代码默认值,Type为-1;请设置Type(表的 Type ID)与需要的字段后再addRow,或像上例一样用getTemplateDef复制原版行。Rows created withnewonly have code defaults andType=-1; setType(the table's Type ID) and the needed fields beforeaddRow, or copy a built-in row withgetTemplateDefas above. - 改写会影响缓存的字段(如船插效果文本)时,同时清除对应缓存,见 hullmodpatch 示例中的
RowUpdate。When changing fields that feed caches (e.g. hull-mod effect text), invalidate those caches too — seeRowUpdatein the hullmodpatch example.
编译Building
- 引用游戏目录
<游戏>_Data/Managed/下的Assembly-CSharp.dll与所需的UnityEngine*.dll。ReferenceAssembly-CSharp.dlland the neededUnityEngine*.dllfrom<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; useconfigfor 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_BuildBean | BuildGenerator,放置建筑生成数据时, when placing a building | FWBuildBean |
generator_BuildClass | BuildGenerator,创建建筑对象时, when instantiating the building object | BaseBuild |
示例: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.