Unity游戏通用mod框架BepInEx生态的工作原理简介

Posted 2023-04-07 __SAD_DOG__

背景

  几个月前, 游戏雨中冒险2 (Risk of Rain2)出了新的DLC, 工作之余跟伙伴联机受受苦还是惬意的。RoR2 这个游戏在设计上的一些机制(比如没有小地图)使得本来操作就不精湛的我经常暴毙。暴毙次数一多就会使得联机游玩毫无游戏体验, 变成雨中看戏。
  作为一名程序员, 心想我刚学的hello world,还能受这气? 于是研究了一下这个游戏的mod机制. 不研究不要紧, 一研究发现八达鸟。社区上似乎很早就有对基于 Unity 开发的游戏的通用mod框架了.虽然之前在博客上看到, 说unity写的游戏基本上就是"开源游戏", 不过亲自看到还是震撼的. 倒是国内的博客对此记录还是很少的(估计游戏公司都在台面下干这个事情).
  与其让游戏公司台面下干这个事情, 倒不如公开发出来, 让热爱游戏的人参与到mod制作中, 为游戏提供更长久的活力.
  本文主要对 BepInEx 及其基本工作原理进行简述, 希望能帮助想了解unity游戏mod开发的人入坑

BepInEx

  BepInEx(github link), 如其github上的官方介绍所属: “is a plugin / modding framework for Unity Mono, IL2CPP and .NET framework games (XNA, FNA, MonoGame, etc.)” 是一个通用的 unity/XNA 游戏mod框架.
  BepInEx及其生态提供了一套几乎可以被称为"SDK"的工具集, 使得开发者只用极少的额外工作(基本上就是下载几个文件并把它们安装在正确的位置)就可以开发游戏的mod代码, 并用自己的代码对unity游戏进行运行时修改. 能做到既不修改游戏的原有代码, 也不修改游戏的启动方式.打上mod之后直接从steam启动也无妨, 甚至其生态系统中还有一些可视化的工具来管理mod.
  接下来就介绍一下BepInEx 是如何做到无痛mod游戏的.

Unity doorstop

  截至目前(2022-08-14), UnityDoortoop(github link)这个用C写的小项目在github只有257个star, 但这不妨碍它在 BepInEx 背后稳定地默默工作.
  整个 unity doorstop工具只有一个 25kb的 winhttp.dll 和一个 doorstop_config.ini 配置文件. 把他们放在unity游戏的根目录下, 在 doorstop_config.ini 配置文件中指定你要先于unity游戏代码启动的代码dll, 你的代码就能在引擎运行目录下的游戏代码之前运行你的代码 “as early as possible.” 具体的实现方式我没有仔细的研究过. 简单看了下C源码体量还是很小的, 但是感觉可能需要对 Unity 进行一些 hack.以后有空可以研究下.
  在 BepInEx 中, UnityDoorstop 充当了 bootstrap 的角色, BepInEx的安装包里, doorstop_config.ini 配置文件里已经指定了 targetAssembly=BepInEx\\core\\BepInEx.Preloader.dll, 于是乎 BepInEx的preloader得以在游戏代码运行前跑起来. 以执行对游戏代码的运行时修改, 加入新的代码等操作.

Preloader, Patcher, Plugin

  上一节中我们已经知道, BepInEx的 preloader.dll 是最先执行的代码. 但是实际上的mod操作当然并不在这个dll中执行. preloader相当于也是一个 bootstrap.
  在概念上, BepInEx 把先于额外加入执行的代码分成两个部分, 分别是 patcher 和 plugin.

patcher

  patcher在 BepInEx/patchers 目录中. 其主要功能是对 BepInEx 进行额外的补充, 比如增加一个控制台, 增加一个可视化的界面查看游戏内对象, 增加暂停游戏的功能等等.

plugin

  plugin 就是你自己写的游戏mod代码了. 在类关系上继承自 BepInExUnityPlugin, (在mono架构下的unity游戏中, BepInExUnityPlugin 继承自 MonoBehavior, 以至于你能使用所有的MonoBehavior生命周期函数). 与patcher不同的是, plugin的代码主要表达的是游戏相关的内容, 而不是 BepInEx 相关的内容.

Monomod.HookGenPatcher

  正如其名字中的 patcher 所指明的, Monomod.HookGenPatcher 作为一个 BepInEx 的 patcher 存在, 这个文件的主要作用是通过 C# 平台的事件机制提供了更加方便的修改游戏的方式. 其工作流是基于 MonoMod 这一项目的. 但是需要注意的是, 虽然作为 BepInEx 生态中的一环, Monomod.HookGenPatcher 被频繁作为patcher使用, 但是 Monomod.HookGenPatcher 是由个人开发者完成的, 并不是 BepInEx 的官方 patcher. (这也是开源社区生态的魅力吧, 齐心协力众人拾柴).
  在第一次使用 BepInEx 运行游戏的时候, Monomod.HookGenPatcher 会扫描游戏代码, 并生成 BepInEx\\plugins\\MMHOOK\\MMHOOK_<your game>.dll. (当然你也可以手动执行MonoMod.exe来完成这一操作). 然后在开发plugin代码的时候, 把 MMHOOK_<your game>.dll 作为 reference, 就可以使用里面的代码监听游戏事件了, 非常的方便, 真正的无痛mod.

结语

  开源社区yyds. 话不多嗦, 操作起来.

ps

  工作之后很久没写博客了, (看了下自己以前的博客虽然很青涩, 但是也很热血) 感觉这种有意思的东西还是可以抽时间写一写的.加粗样式

Modding Unity Games

前言：

对游戏进行修改与拓展（MOD）是我一直以来感兴趣的东西，我的程序生涯，也是因为在初中接触到GBA口袋妖怪改版开始的，改过也研究过一些游戏的MOD实现方式，早就想在自己的游戏中实现“MOD系统”以便支持玩家对我的游戏进行修改，无奈太懒一直没动手，最近在研究U3D游戏的HACK方式，顺便也看了几篇U3D游戏MOD的文章，整理一下算是给自己将来的“MOD化游戏框架”做点提取规划。

 

先上几篇博客以及做点笔记：

1.How easy is it to allow for modding in a Unity game?

So the first one is often overlooked by people and this is quite tricky to do, as when you load your current game, what do you do? I assume you load a scene which is your main menu. However this is a hardcoded thing, if your mod is an entire game you want to show the mods main menu not yours, so how do you go about doing this? You can basically do a DLL scan of a given folder or expect some command line arg or something to trigger it, however what if your mod is just adding a feature to your existing game (i.e world of warcraft mods), how do you achieve partial modding while keeping the underlying game the same? Generally you would have an event based system where all component interactions raise events, and these mods when loaded subscribe and either proxy or completely take over the handling of those events. Such as adding a god mode to you game via a mod would require you to either proxy the OnEntityDamage events or ignore them so the entity does not take damage etc.

 

2.Let‘s talk about modding Unity games.

 

3.Creating A Moddable Unity Game

 

4.Github Unity-CSharp-Mod