更新

.agents/skills/game-designer-generic/knowledge/UMod_2.0_系统详解.md

@@ -0,0 +1,256 @@
+# 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` 会发出警告。