Jump to content

Mutagen / Synthesis Test Drive

Recommended Posts

Mutagen is an object-oriented framework for parsing and generating Bethesda game plugins. Synthesis patchers are programs built on top of the Mutagen framework for a specific purpose. Both are written in the C# language. Similarly to zEdit or xEdit patcher scripts, they allow for analyzing an entire load order worth of plugins and producing a specific patch algorithmically.

Synthesis patchers come in 2 forms: standalone .exe executable, or source code.

I first tried one of the standalone patchers distributed on Nexus but it auto-detects the game Data folder location based on the Windows registry setting, while my modded SSE installation is stored in a separate folder in a non-standard location not managed by Steam.

The patcher auto-detected and ran on my unmodded SAE installation. So that experiment didn't go very far and I can't speak of its results, which were nil. When run from MO, the standalone patcher runs quickly in a console window that closes immediately upon completion, making it difficult to see what went on.

Using a standalone patcher may be fine if a single one is needed, however using the hub GUI should be preferable for combining multiple patchers, reducing the number of plugins generated and benefitting from the "pipelining" mechanism.

I then switched to the hub GUI.

  • It requires the .NET 6 SDK in order to compile source code patchers into executable form. The SDK needs to be downloaded and installed separately, as it's a developer tool not built into Windows.
  • The UI is pretty nice and fairly easy to use, at least compared to other modding tools. It suffers from "kool flat UI" syndrome: one has to hover everything in order to find out if it's a button or not.
  • Different game profiles (e.g. Skyrim SE, Enderal SE, Fallout 4) can be created and activated, including ones in custom folder locations.
  • The list of available patchers is pulled from a central registry on GitHub. Each individual patcher is downloaded in source code form from its own GitHub repository. There are quite a few patchers, but not many. I expected there'd be more of them given there are thousands of Skyrim SE mods.
  • Most patchers are very "niche" being specialized for one specific mod, or one specific type of change.
  • Multiple patchers can be run in a "pipeline" feeding from one to the next and producing one final combined patch plugin.
  • Some patchers are configurable, either via a settings panel integrated in the hub GUI, or via a configuration file to be edited in a text editor.


I tried a few patchers, some that were relevant to my modlist, others simply out of curiosity:

  1. AI-Overhaul-Patcher*: Forwards NPC changes from AIO and merges them with NPC changes from other mods. As LOOT sorts AIO pretty high in the load order, its NPC changes are likely lost by other mods loaded after it. The patcher seems to work well enough as designed, but I don't agree or don't understand why it doesn't forward some AIO edits. Overall I can do the same or better job manually in xEdit. Admittedly there are only a handful NPCs in STEP that need patching (because of Simple Children and CRF) so it's easy to do manually. The automated patcher may be more useful to players who for example use mods changing the appearance of lots of NPCs.
  2. AOSISCSoundPatcher: Supposed to add sound effects to all weapons & armor of mods in the load order, consistent with the changes in Audio Overhaul Skyrim or Immersive Sound Compendium. This produces absolutely nothing for me, even after disabling all my AOS compatibility patches. I don't really know what to expect - this is one of those patchers with zero documentation.
  3. BreakdownRecipeGenerator: Generate breakdown recipes for all craftable items in a load order. Also provides the option of creating custom breakdown recipes for miscellaneous items, weapons and armors. This seems to work quite well, it generated breakdown recipes for seemingly every object. The only problem is I have no idea why I would need them or what I would do with them.
  4. enblightpatcher: Tweak all light sources for ENB Light compatibility. This is a pretty extensive patcher that modifies the lighting properties of certain cells and of all light sources, of all mods in the load order, making them less bright. It's useless to me as I don't use ENB, but it's a good example of what can be done efficiently and reliably. It beats having to edit every single candle or torch in the game manually in xEdit.
  5. ExperienceMutagenPatcher: Generates an Experience XP configuration file for killing races or NPCs added by mods in the load order. Appears to be functional. I intend to use the other patcher described further down rather than this one.
  6. facefixer: Supposed to patch NPCs to fix the 'black face' bug. It definitely does something, but in the STEP modlist, the only mod that changes NPC appearance is Simple Children and there is no black face issue, so patching is unnecessary. Probably useful to players using a lot of NPC beautification mods.
  7. leveledlistresolver: Merges levelled lists, like Wrye Bash, without relying on Bash tags. Appears to work quite well and to be pretty smart. I have to manually merge levelled lists in xEdit because Wry Bash produces a complete mess whenever I use it. I was quite happy to see this patcher produced results identical to mine, even better, it caught a list I missed.
  8. Realistic-Water-Two-Patcher: Forwards changes from RWT so they don't get overwritten by other mods. Similar to AI-Overhaul-Patcher above, except this one is dumb and rewrites all RWT-modified records, whether they are overwritten or not, producing a huge patch.
  9. Requiem-Experience: Generates an Experience XP configuration file and patch plugin, to be used along with Requiem - or any other overhaul which makes Skyrim world to be un-levelled. This is a more feature-rich patcher than the ExperienceMutagenPatcher above. Good documentation and customization options. I only used a subset of its options with a simple vanilla-like setup (no Requiem, no unlevelling overhaul), but it produced useful results.

As with any automated tool like Mator Smash or Wrye Bash, it's a good idea to review the generated patches in xEdit, at least cursorily, to verify the results look ok.

Overall, I'm not too impressed but there's definitely some potential and I found some useful patchers on offer, which I'm going to rely on in the future. Quality appears to vary greatly, the most disappointing aspect for me being the total lack of documentation for many patchers. It's all open-source, so sure, it's possible to read the source code to figure out how a given patcher works, but not everyone can read and reverse-engineer C#, or spend the time to do it.

On the plus side, the patching process is pretty easy to set up. Once set up, the whole patching pipeline can be run again from MO whenever a mod is added or removed, and it's quite fast (compared to manual editing in xEdit). In theory it can support huge load orders.

On the minus side, the fact that patchers are actual programs, written C#, represents a high obstacle to making a patcher.

The Mutagen/Synthesis toolset could be quite useful to automatically generate configuration files for SPID, Base Object Swapper, Keyword Item Distributor, and similar framework mods, based on all mods in a given load order.

(*) Before actually trying out the AI Overhaul patcher, I wildly imagined that it would be capable of applying AIO changes to new NPCs from other mods. I was completely wrong and in retrospect, I realize this would be impossible. How could a particular NPC behavior be assigned to an unknown NPC from an unknown mod? Perhaps via the use of specific keywords to 'tag' mod-added NPCs. That might work. In any case, the AIO patcher doesn't work like that at all, it only deals with NPCs that AIO supports 'out-of-the-box' in its plugin.

Link to comment
Share on other sites

Thanks for the write-up. It sounds like Mutagen/Synthesis may be the way to go if/when patchers evolve for mods of interest (Requiem for me). I like the ELE and ENB Light patcher concepts. Need one for TCIY and CACO!

Could get really interesting as it evolves.

Link to comment
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

  • Create New...

Important Information

By using this site, you agree to our Terms of Use.