如何让你的 Unity 游戏跑起 MOD：MelonLoader 模组加载器完全指南-开发者社区

如何让你的 Unity 游戏跑起 MOD：MelonLoader 模组加载器完全指南

【免费下载链接】MelonLoaderThe World's First Universal Mod Loader for Unity Games compatible with both Il2Cpp and Mono项目地址: https://gitcode.com/gh_mirrors/me/MelonLoader

你给一款 Steam 游戏找到了心仪的模组，却发现游戏是 Il2Cpp 架构、目录里没有任何 C# 程序集，模组根本装不进去。MelonLoader 就是一个同时支持 Il2Cpp 和 Mono 双架构的 Unity 游戏模组加载器：不改游戏一行代码，把两个文件拷进游戏目录，游戏启动时就会弹出控制台，自动发现并加载Mods文件夹里的所有模组。

先花 30 秒判断：你的游戏能不能跑

MelonLoader 的兼容性覆盖两种 Unity 编译架构，平台支持情况如下：

唯一的硬性前提按架构区分：

Il2Cpp 游戏：需要安装 .NET 6.0 Desktop Runtime，Windows 下会自动安装，其他平台需自备
Mono 游戏：无额外要求，启动时由内置的 Mono 运行时直接接管

只需往游戏目录拷两个文件：手动安装

以官方发布包为例，完整流程只有 3 步：

确认游戏已完全关闭
把压缩包里的MelonLoader文件夹解压到游戏安装目录
把压缩包根目录的version.dll和dobby.dll也解压到与游戏主程序同级

这里的关键是version.dll——它是一个代理 DLL（Proxy），利用 Windows 会优先加载同名系统库的特性，在游戏启动瞬间把 MelonLoader 本体带进进程。如果某些游戏不认这个名字，可以把它重命名为winmm.dll、dinput8.dll、d3d9.dll、dsound.dll等，完整的 14 个可选名称可以在MelonLoader.Bootstrap/Proxy/Exports/目录里逐一对照，那里为每个名称都实现了导出函数。

第一次启动：你会看到什么

游戏正常进入后，有三样东西值得认识：

启动画面：加载期间播放动画 Logo，源码在Dependencies/MelonStartScreen/，支持 "Normal" 和 "Lemon" 两套主题
悬浮控制台：实时显示模组注册顺序、加载进度，颜色对应不同模组
日志与配置：所有日志写入游戏目录下的MelonLoader/Logs；配置文件UserData/Loader.cfg在第一次运行后才会生成

加载顺序不是随机的：MelonLoader/InternalUtils/DependencyGraph.cs会先按声明的依赖做拓扑排序，再用MelonPriorityAttribute排优先级，结果都会打印在控制台里。

写你的第一个模组：五行 C#

模组就是一个继承自MelonMod（定义在MelonLoader/Melons/MelonMod.cs）的类，编译出的 dll 放进Mods文件夹即可：

[MelonInfo(typeof(MyMod), "MyMod", "1.0.0", "me")] public class MyMod : MelonMod { override public void OnInitialize() => MelonLogger.Msg("Hello from MyMod!"); }

几个要点：

[MelonInfo]里的名称、版本、作者是必填项，版本遵循 SemVer 规范（解析逻辑见MelonLoader/Attributes/MelonInfoAttribute.cs）
生命周期回调如OnInitialize、OnSceneWasLoaded直接覆写即可，事件定义集中在MelonLoader/MelonEvents.cs
改游戏逻辑不用改原代码：内置 Harmony（0Harmony，兼容层在MelonLoader/BackwardsCompatibility/Harmony/），对方法打前缀/后缀补丁
Il2Cpp 游戏的特殊处理：首次运行时Dependencies/Il2CppAssemblyGenerator/会基于 Cpp2IL 和 Il2CppInterop 从原生代码反推出一套 C# 程序集，供你的模组引用
顺带一提，Dependencies/CompatibilityLayers/还内置了对 Illusion 系 IPA、Muse Dash、Stress Level Zero 等旧模组框架的包装，老模组也能跑起来

给模组配一个设置面板：TOML 偏好系统

MelonLoader 的偏好系统（MelonLoader/Preferences/）让模组作者可以声明式地创建配置项，自动落盘为 TOML 文件，玩家改文件后自动热更新，重启后保留。核心 API 就两步：

[MyMod] sensitivity = 0.75 show_hud = true

var cat = MelonPreferences.CreateCategory("MyMod", "MyMod 设置"); var entry = cat.CreateEntry<float>("sensitivity", 1.0f, "灵敏度");

每个条目可以附默认值、显示名和校验器（ValueValidator），非法值会被拒绝而不是让模组崩掉。

常用 Loader.cfg 配置项对照表

UserData/Loader.cfg中的每个配置项都有等价的启动参数，两处任选其一：

完整的启动参数表（含 Cpp2IL、Mono 调试服务器等）都在README.md的 LAUNCH OPTIONS 一节里。

模组不加载时：日志在哪、怎么对比排查

按顺序做，基本能定位 90% 的问题：

看日志：MelonLoader/Logs里最新一份，失败原因写得很直白。加载失败的模组会被标记为"烂瓜"（RottenMelon，见MelonLoader/Melons/RottenMelon.cs），日志里会有对应条目
隔离对比：用--no-mods启动，确认游戏本体正常；再逐个移除模组做二分
开调试模式：debug_mode = true时控制台输出更详细；Il2Cpp 游戏还可以设launch_debugger = true直接挂调试器
确认版本匹配：CHANGELOG.md记录了每个版本的行为变更，模组要求的加载器版本与当前版本（最新为 v0.7.3）不一致时，先看这段记录

下一步去哪

查参数：README.md里有全部配置项、启动参数和代理 DLL 命名表
参与开发：源码用dotnet构建，根目录compile.sh封装了跨平台编译流程（参数为版本号、RID、配置）

git clone https://gitcode.com/gh_mirrors/me/MelonLoader

跟进版本：CHANGELOG.md和RELEASE-NOTES.md同步更新，项目采用 Apache 2.0 许可

【免费下载链接】MelonLoaderThe World's First Universal Mod Loader for Unity Games compatible with both Il2Cpp and Mono项目地址: https://gitcode.com/gh_mirrors/me/MelonLoader

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考