Skip to content

Home

Mutagen is a C# library for analyzing, modifying, and creating Bethesda mods. One of its main features is offering interfaces and classes for the records that exist at compile time and are first class citizens in C#. With actual members for each field they get the benefits of type safety, simple live debugging, Intellisense features such as autocomplete. The interfaces offer clean API to the user and abstract away much of the binary record specifics and oddities of how they are stored on disk, while the actual implementation remains very closely tied to the data offering as much speed as it can by leveraging some of the latest C# features. Most of the public facing API is created by code generation, with small manual snippets of code for the one-off special cases. This means the library is able to provide consistent API with very little manual work when adding new record definitions or features.

Goals

What is Mutagen trying to provide?

  • Ability to analyze, create, or manipulate Bethesda mods in C#.
  • Strongly typed objects and fields for all records, which naturally offer Intellisense and type safety.
  • User abstraction from complex binary record structures/patterns, when appropriate and beneficial.
  • Frameworks for accomplishing common tasks
  • Performance via intelligent short circuiting of work and minimal internal layers underneath the API.
  • Heavy use of generated code to provide the above goals without requiring verbose manual development or maintenance.
  • Powerful but gritty low level tools for those that want to forgo the autogenerated classes for special tasks.

Sample API

A small snippet showing how to print some EditorIDs 

// A function that loops over any major records, and prints their unique EditorIDs
void PrintAll(IEnumerable<IMajorRecordCommonGetter> records)
{
    foreach (var editorId in records
        .Select(record => record.EditorID)
        .Where(edid => !edid.IsNullOrWhitespace())
        .Distinct())
    {
        System.Console.WriteLine(editorId);
    }
}

// Create a bootstrapping state object with entry points for a typical installation
using var env = GameEnvironment.Typical.Skyrim(SkyrimRelease.SkyrimSE);
// Print all winning override weapon from all active mods in the game
PrintAll(env.LoadOrder.PriorityOrder.Weapon().WinningOverrides());

// Print all armors from a specific mod
using var mod = SkyrimMod.CreateFromBinaryOverlay(Path.Combine(env.DataFolderPath, "MyMod.esp"));
PrintAll(mod.Armors);

Major Features

Plugins

Importing, exporting, and manipulating plugins (esp/esm.esl files)

Linking and Record Lookups

Following FormID pointers and looking up records by FormID/FormKey/EditorID

Load Order

Accessing the order mods should load and override one another

  • Read/Write support
  • Live monitoring that adapts to on-disk changes
  • Winning Override Iteration

Archives (Bsa/Ba2)

Extracting assets from archive files

  • Read support

Strings

Multi language string support systems

WPF UI Controls

Controls that can be used in any WPF app

  • FormKey Pickers
  • ModKey Pickers
  • Load Order display and manipulation

Seeing Mutagen in Action

Synthesis

Synthesis is a patcher pipeline built on top of Mutagen, and it already has a large library of example patchers to study and get inspiration from.

Example Project

Another option is the Mutagen Bootcamp project. It contains a good number of example tasks which you can run after pointing it to your copy of Skyrim. It should be a good starter to help you understand the basics and actually see some of the processing in action.

Installing Mutagen

Mutagen can be added to your C# project via NuGet, under the package name Mutagen.Bethesda. Search for it in Visual Studio, or find it here.

If you're unfamiliar with setting up C# projects in general, a good place to start might be creating a simple Synthesis patcher, and be sure to ask questions on our Discord.