ADOFAI UnityMod 模板

这是一个只服务于《A Dance of Fire and Ice》（ADOFAI）的 UnityModManager 模板。 它的目标是让你用一条 dotnet new 命令得到一个可以继续开发的 Unity 工程，而不是把某个作者电脑上的游戏 DLL 和缓存一起复制给你。

快速开始

前置条件：

• Windows
• Unity 6000.3.10f1
• .NET SDK
• 已安装 ADOFAI、UnityModManager 和 Git
• 工程会通过 Packages 配置获取 ThunderKit

如果已经克隆了模板仓库，在仓库目录执行：

dotnet new install .
dotnet new list

其他人可以从 GitHub 获取模板后安装：

git clone https://github.com/StArraySharp/ADOFAI-UnityModTemplate.git
dotnet new install .\ADOFAI-UnityModTemplate
dotnet new list

dotnet new install 不能直接把 GitHub URL 当作模板包；也可以下载发布的 .nupkg 后直接安装。

然后创建 Mod：

dotnet new adofaimod `
  --name MyCoolMod `
  --output MyCoolMod `
  --game-path "C:\Games\ADOFAI\A Dance of Fire and Ice.exe" `
  --author-name "Your Name" `
  --description "My ADOFAI mod" `
  --version "1.0.0"

项目名必须符合 C# 标识符规则：^[A-Za-z_][A-Za-z0-9_]*$。.NET 的 dotnet new 主程序已经占用了 -a/--author 作为模板筛选参数，所以原生命令使用 --author-name；仓库中的包装脚本仍提供计划中的 -a 写法，并会把它转换成正确的模板参数。如果希望在生成前同时检查项目名、游戏 exe 和 _Data/Managed，请使用包装脚本。

.\New-ADOFAIMod.ps1 `
  -n MyCoolMod `
  -o MyCoolMod `
  -g "C:\Games\ADOFAI\A Dance of Fire and Ice.exe" `
  -a "Your Name" `
  -d "My ADOFAI mod" `
  -v "1.0.0"

完整初始化、目录说明和故障排查见 docs/GettingStarted.md。

第一次打开 Unity

打开生成目录后，Unity 会自己生成 .slnx、.csproj、Library 等编辑器产物，这些文件不属于模板源代码。

模板编辑器脚本会读取 ProjectSettings/ADOFAI.Template.local.txt 中的 exe 路径，检查游戏文件，并把它拆成 ThunderKit 需要的：

• GamePath：ADOFAI 所在目录
• GameExecutable：exe 文件名

随后会打开 ThunderKit Settings。你只需要点击一次 Import，让 ThunderKit 从本机游戏生成 Packages/A Dance of Fire and Ice/。这个目录包含本机游戏程序集，只在本机使用，不提交到 Git。

目录约定

Assets/
├── Editor/                  编辑器初始化和构建工具
├── Scenes/                  以后放 Unity 场景，进入 scenes.assets
├── Scripts/                 Mod C# 代码和项目同名 asmdef
└── Resources/               以后放资源
    ├── Prefabs/
    ├── Textures/
    ├── Materials/
    ├── Shaders/
    ├── Audio/
    ├── Fonts/
    ├── UI/
    ├── Animations/
    └── ScriptableObjects/

模板不携带示例场景、示例资源或 Hello World 逻辑。Main.cs 负责 Mod 生命周期，Patches.cs 是 Harmony 补丁入口，ResourceLoader.cs 负责两个 AssetBundle 的加载和释放。

模板脚本怎么分工

生成项目后，通常按下面的方式使用这些文件：

文件	作用
Main.cs	UnityModManager 入口，负责启用/禁用 Mod、应用补丁和加载资源
ModSettings.cs	添加 UnityModManager 设置字段和设置界面
Patches.cs	编写 Harmony 补丁，修改游戏行为
ResourceLoader.cs	加载和释放 ThunderKit 生成的 scenes.assets、resources.assets
TemplateBootstrap.cs	第一次打开 Unity 时自动配置 ThunderKit；只在编辑器中运行
BuildMod.cs	执行 ThunderKit 构建，并把 Mod 文件复制到游戏的 Mods 目录
<ProjectName>.asmdef	指定程序集名称、命名空间和游戏 DLL 引用
Info.json	告诉 UnityModManager Mod 的名称、版本、DLL 和入口方法

启用 Mod 时的基本流程是：Main.Load 注册生命周期回调，用户启用 Mod 后由 Main 调用 Harmony 应用补丁，再由 ResourceLoader 加载资源包；禁用时撤销补丁并释放资源。模板故意不提供示例补丁、示例设置或示例资源。

脚本的完整说明、代码示例和资源加载方式见 模板脚本与资源使用。

构建

Unity 完成 ThunderKit 导入后，在菜单中打开 Tools > Build Mod。选择 ThunderKit Pipeline 和输出目录，然后点击 Build Mod。默认输出目录是 ADOFAI 安装目录下的 Mods/<ProjectName>/。

构建窗口只部署以下文件：

<ProjectName>.dll
Info.json
scenes.assets
resources.assets

它不会复制游戏 DLL，也不会自动启动游戏。

打包模板

直接从 Git 仓库安装：

dotnet new install .

生成 NuGet 模板包：

dotnet pack .\ADOFAIModTemplate.Template.csproj -c Release
dotnet new install .\artifacts\StArraySharp.ADOFAIUnityModTemplate.1.0.0.nupkg

打包时会排除 Git、Unity 缓存、ThunderKit 构建输出、本机游戏包、模板本身的打包辅助文件和本地游戏路径配置。

参考

• .NET 自定义模板文档
• ThunderKit 导入流程