# UMod 2.0 系统详解

> **来源**：uMod 2.0 UserGuide.pdf + UMod Plugin XML API 文档 + ExampleScripts  
> **整理日期**：2026-03-13  
> **适用角色**：游戏设计师、技术员、Mod 制作者  
> **本文档用途**：供所有团队成员快速掌握 UMod 的核心机制、API 风格与 Continentis 项目中的具体应用模式

---

## 一、UMod 是什么？

UMod 2.0 是一款 Unity 插件，让游戏开发者能够**在发布后的游戏中支持社区 Mod**。其核心目标是：

- 允许 Modder 在独立的 Unity 项目中创建内容（资产、脚本、场景）
- 将内容打包为单个 `.umod` 文件
- 游戏在运行时动态加载该文件并使用其中的内容

**重要限制**：UMod **不支持 IL2CPP**（因为 IL2CPP 禁止运行时动态加载程序集）。因此使用 UMod 的游戏必须使用 **Mono 后端**。

---

## 二、核心概念与术语

| 术语 | 说明 |
|---|---|
| **ModHost** | 管理单个 Mod 生命周期的核心对象。负责加载、卸载、资产访问、脚本访问 |
| **Mod.Load()** | 静态方法，传入 Mod 路径 URI，返回一个 `ModHost` 实例 |
| **host.Assets** | 访问 Mod 中所有打包资产的接口（类似 `Resources.Load`）|
| **host.IsModLoaded** | 布尔值，判断 Mod 是否已成功加载 |
| **host.LoadResult** | 包含 `ModLoadError` 枚举，详细描述加载失败原因 |
| **ModDirectory** | 指定游戏扫描 Mod 的目录路径（如 `persistentDataPath + "/Mods"`）|
| **ModSearch** | 扫描目录以发现有效 `.umod` 文件的组件 |
| **ModManifest** | Mod 内部的元数据资产（名称、版本、作者等），可在加载前读取 |
| **ModInfoResource** | 在加载 Mod 前即可读取的外部信息（通过 `ModSearch` 获取）|
| **ModObjectIdentity** | 自动附加到 Mod 内所有对象上的组件，供 Host 追踪和管理 Mod 对象生命周期 |
| **LinkBehaviour** | 存储 Mod 脚本的类型信息，使 Host 可以在运行时重新链接正确的 C# 类 |

---

## 三、Mod 加载流程（完整步骤）

```
1. [搜索] ModSearch 扫描目录，发现 .umod 文件
        ↓
2. [加载前预读] 通过 ModInfoResource 读取 Mod 元数据（名称、版本、依赖）
        ↓
3. [加载触发] ModHost host = Mod.Load(new Uri(modPath));
        ↓
4. [UMod 内部处理]
   a. 读取并挂载 AssetBundle
   b. 加载 Mod 内的程序集（.dll 或编译后的 .cs）进入 AppDomain
   c. 通过 LinkBehaviour 重新链接所有脚本组件到对应 C# 类型
   d. 触发 ModObjectIdentity.OnModObjectCreated 事件
        ↓
5. [就绪状态] host.IsModLoaded == true
        ↓
6. [资产访问] host.Assets.Load<T>("资产名称")
        ↓
7. [类型访问] host.Assets.Load<MyScriptableObject>("数据名称")
        ↓
8. [卸载] host.UnloadMod() → 自动销毁所有已追踪的 Mod 对象
```

### 常见加载错误码（ModLoadError）

| 错误码 | 原因 |
|---|---|
| `NoError` | 成功 |
| `InvalidMod` | 文件损坏或非 UMod 格式 |
| `InvalidPath` | 路径无效 |
| `ModNotFound` | 路径有效但文件不存在 |
| `MissingReferences` | Mod 依赖的其他 Mod 未加载 |
| `SecurityError` | Mod 脚本违反了 Host 设置的安全白名单 |
| `UnityVersionIncompatibility` | Unity 版本不匹配 |

---

## 四、C# 脚本在 Mod 中的工作方式

### 4.1 脚本打包方式

Mod 可以通过两种方式包含 C# 逻辑：

1. **源码（.cs 文件）**：UMod 在导出时将 Modder 编写的 .cs 文件编译为临时程序集 `uMod.Scripts`，打包进 .umod 文件。加载时在运行时进行再次编译。
2. **预编译 DLL**：Modder 也可以提供预编译的 `.dll` 文件，UMod 直接将其加载进 AppDomain。这是 Continentis 当前的实际工作方式（查看项目根目录下的 `umod-compiled-*.pdb` 文件）。

### 4.2 Host 如何访问 Mod 脚本中的类型

```csharp
// 方式1：通过 ModManager（Continentis 项目的封装层）
Type logicType = ModManager.GetType(typeID);
object instance = Activator.CreateInstance(logicType);

// 方式2：通过 UMod 原生 API（获取所有实现了某接口的类型实例）
IEnumerable<IMyInterface> instances = host.GetInstances<IMyInterface>();

// 方式3：通过 ScriptDomain（直接访问脚本程序集中的类型）
Type[] allTypes = host.ScriptDomain.GetTypes();
```

### 4.3 在 Continentis 中的具体应用

Continentis 的 `ModManager` 类封装了 UMod 的类型访问，格式为：

```
TypeID = "{ModName}/{Category}/{SubCategory}/{ClassName}"
例如："Basic/Cards/Assassin/Backstab"
```

这使得 **CardData**（纯数据）与 **CardLogicBase**（行为代码）可以独立来自不同 Mod，实现了真正的数据-逻辑解耦。

---

## 五、资产的打包与访问

### 5.1 打包规则

- Mod 内所有资产通过 Unity 的 **AssetBundle** 系统打包
- 打包时 UMod Exporter 会自动为每个 GameObject 附加 `ModObjectIdentity` 组件
- 资产名称即为 Unity 编辑器中的资产文件名（不含扩展名）

### 5.2 资产访问 API

```csharp
// 检查资产是否存在
bool exists = host.Assets.Exists("资产名");

// 加载资产（同步，类似 Resources.Load）
GameObject prefab = host.Assets.Load("prefab名") as GameObject;
ScriptableObject data = host.Assets.Load<MyData>("数据名");

// 实例化（必须先实例化才能使用 GameObject，否则会影响编辑器）
GameObject instance = Instantiate(prefab, Vector3.zero, Quaternion.identity);

// 在 Continentis 的 ModManifest.SaveToDatabase 中的实际用法：
T data = host.Assets.Load<T>(assetName);
ModManager.Database[typeof(T)].TryAdd(assetName, data);
```

### 5.3 支持的资产类型

- Prefabs、Materials、Textures、Audio、Sprites
- **ScriptableObject**（必须在 Mod 项目中创建，不能在运行时用代码创建）
- Scenes（场景也可以打包）
- AnimationClips、Fonts 等 Unity 原生资产类型

---

## 六、Shared API（共享接口层）概念

**这是 Mod 系统设计中最关键的架构概念。**

### 6.1 什么是 Shared API

Shared API 是 Game → Modder 的**契约层**。游戏开发者将所有"Mod 可以继承或实现的基类"打包成一个单独的 DLL（或源码），Modder 在自己的 Unity 项目中**引用**这个 DLL，即可编写符合主游戏期望的 Mod 脚本。

### 6.2 在 Continentis 中的对应关系

| Shared API 层 | Continentis 实现 |
|---|---|
| Mod 可继承的基类 | `CardLogicBase`、`CharacterLogicBase`、`CharacterCombatBuffBase`、`IntentionBase` 等 |
| Mod 可使用的工具类 | `CardAssistanceFunctions`、`CharacterAssistanceFunctions` 等 |
| 数据定义类 | `CardData`、`CharacterData`、`EquipmentData`（ScriptableObject）|
| API 访问层 | `ModManager`、`CombatMainManager`、`CombatUIManager` 等 Singleton |
| 命令系统 | `CommandBase`、`CommandGroup`、`Cmd_*` 系列命令类 |

这些类合在一起，就是 Continentis 事实上的"Shared API"，但它们目前**并没有被正式打包为独立 DLL** 分发给 Modder。

---

## 七、安全等级（Security Level）

UMod 提供三种脚本安全策略（在 Host 端配置）：

| 策略 | 说明 | Continentis 建议 |
|---|---|---|
| **Allow All** | 不做任何检查，Mod 脚本可以访问任意 C# API | 仅开发阶段使用 |
| **Reject Only Specified** | 黑名单模式，明确禁止某些危险 API（如 `System.IO`、`System.Net`）| 对外发布时的妥协方案 |
| **Allow Only Specified** | 白名单模式，仅允许明确指定的命名空间/类型 | 最安全，但配置成本高 |

**Continentis 注意**：由于开发者明确允许不加密并可暴露源码，建议对内部测试 Mod 使用 **Allow All**，若未来开放社区则切换为 **Reject Only Specified**，将 `System.IO.File`、`System.Net.*`、`System.Reflection.Emit` 等列入黑名单。

---

## 八、ModTools（Modder 工具链）

### 8.1 游戏开发者需要提供给 Modder 的内容

通过 `Tools → uMod 2.0 → Mod Tools Builder` 在 Unity 编辑器中生成 **Mod 制作专用工程**，其中包含：

1. **Shared API DLL**（或源码）—— Modder 引用此 DLL 来继承游戏基类
2. **UMod Exporter**（编辑器工具）—— Modder 用来将自己的 Unity 项目打包为 `.umod` 文件
3. **示例 Mod 项目**（可选）—— 供 Modder 参考的模板

### 8.2 Modder 的标准工作流

```
1. 新建 Unity 项目（必须与主游戏使用同一版本的 Unity）
2. 导入 Shared API DLL
3. 导入 UMod Exporter 工具
4. 创建 CardData.asset（ScriptableObject）- 填写卡牌数值
5. 编写 MyCard.cs（继承 CardLogicBase）
6. （可选）创建卡牌图片、动画、音效等资产
7. 通过 UMod Exporter 一键打包为 MyMod.umod
8. 将 .umod 文件放入游戏的 Mods 目录
```

---

## 九、Mod 包的内部结构

一个 `.umod` 文件（本质是 AssetBundle 自定义格式的归档）包含：

```
MyMod.umod
├── [ModInfo]          ← 元数据：名称/版本/作者/依赖/Unity版本等
├── [AssemblyInfo]     ← 枚举本 Mod 包含的所有程序集
├── Assembly-CSharp.dll（或编译后的 .cs）
│   └── 包含所有 Modder 编写的 C# 类
├── ScriptableObject 资产（CardData.asset 等）
├── Prefab 资产（角色模型、特效等）
├── Sprite/Texture 资产（卡牌图片等）
└── [ModObjectIdentity] 信息（存储于各 Asset 中）
```

---

## 十、关键限制与注意事项

1. **IL2CPP 不兼容**：必须使用 Mono 脚本后端（Build Settings 中确认）
2. **ScriptableObject 只能在 Mod 项目中创建**，不能在运行时通过代码 `ScriptableObject.CreateInstance<T>()` 创建然后注册（因为 AssetBundle 需要序列化这些资产）
3. **Unity 版本锁定**：Modder 必须使用与主游戏完全相同的 Unity 版本，否则会出现 `UnityVersionIncompatibility` 错误
4. **GameObject 必须实例化**：从 `host.Assets.Load<GameObject>()` 取到的是 Prefab 原始资产，必须通过 `Instantiate()` 才能放入场景使用
5. **`[SerializeField]` 的序列化限制**：Mod 脚本中 `[SerializeField]` 标记的字段，其类型必须是主游戏已知的类型或 Unity 原生类型，否则无法正确序列化
6. **Mod 间依赖**：一个 Mod 可以声明依赖另一个 Mod（通过 ModManifest 的依赖列表），加载时 UMod 会检查依赖是否已加载

---

## 十一、在 Continentis 中的应用现状

### 当前 Basic Mod 的工作方式（编辑器内模式）

Basic Mod 目前**不是外部 .umod 文件**，而是直接作为 `Assembly-CSharp` 的一部分运行在编辑器内。这是 UMod 支持的"In-Editor Mod"模式，用于开发阶段便捷测试。

实际外部 Mod 文件存放于 `Assets/ExportedMods/` 目录，并对应在根目录有大量的 `umod-compiled-*.pdb` 符号文件，说明已有若干编译产物。

### Mod 资产命名规范（当前项目约定）

```
{AssetType}_{ModName}_{AssetName}
示例：CardData_Basic_Backstab
      CharacterData_Basic_Assassin
      EquipmentData_Basic_SteelBracer
```

命名必须符合 `^\w+_\w+_.+$` 正则，否则 `ModManifest` 会发出警告。