Taosecurity.Starfield.BuildKit 0.2.0

dotnet add package Taosecurity.Starfield.BuildKit --version 0.2.0
                    
NuGet\Install-Package Taosecurity.Starfield.BuildKit -Version 0.2.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Taosecurity.Starfield.BuildKit" Version="0.2.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Taosecurity.Starfield.BuildKit" Version="0.2.0" />
                    
Directory.Packages.props
<PackageReference Include="Taosecurity.Starfield.BuildKit" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Taosecurity.Starfield.BuildKit --version 0.2.0
                    
#r "nuget: Taosecurity.Starfield.BuildKit, 0.2.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Taosecurity.Starfield.BuildKit@0.2.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Taosecurity.Starfield.BuildKit&version=0.2.0
                    
Install as a Cake Addin
#tool nuget:?package=Taosecurity.Starfield.BuildKit&version=0.2.0
                    
Install as a Cake Tool

BuildKit

BuildKit is a small C# library for programs that build Starfield plugins (.esm files) with Mutagen. It holds the setup code such a builder otherwise copies from project to project: opening masters with the right flags, writing the plugin the way the Creation Kit does, filling effect data Mutagen leaves out, keeping FormIDs fixed between builds, and adding a "Show Debug Messages" option.

It targets Mutagen.Bethesda.Starfield 0.54.4 exactly. Each BuildKit release says which Mutagen version it was tested with; a new Mutagen release gets a new BuildKit release.

Install

dotnet add package Taosecurity.Starfield.BuildKit

BuildKit needs .NET 9 and brings Mutagen.Bethesda.Starfield 0.54.4 with it.

Quick start

using BuildKit;
using Mutagen.Bethesda;            // AddNew and other group helpers
using Mutagen.Bethesda.Starfield;

var dataDir = @"C:\Program Files (x86)\Steam\steamapps\common\Starfield\Data";
using var game = new GameData(dataDir);
game.Open("Starfield.esm");                      // plus any other master, e.g. game.Open("SFBGS003.esm")

var mod = Plugin.New("MyMod.esm", PluginStyle.Light, "Your Name", "My Mod 0.1.0");
var kw = mod.Keywords.AddNew("MM_Keyword");      // ... your records ...
var vanilla = game.Get<IKeywordGetter>("SomeVanillaKeyword");   // EditorID lookups across the open masters

var dbg = GameplayOptions.Debug(mod, "MM_Option_Debug", "My Mod's log lines on screen");
GameplayOptions.Group(mod, "MM_Options", "My Mod", [dbg]);

Console.WriteLine(IdLock.Apply(mod, "ids.lock.json"));   // commit ids.lock.json with your builder
PluginWriter.Write(mod, "out", game);                    // writes out\MyMod.esm

What's in it

Type What it does
GameData Opens masters from the Data folder (and optional extra folders searched first). Each master's own masters are opened before it, with their light, medium or full flags, so FormIDs resolve correctly. Gives EditorID lookups (Get<T>, where a later master wins), a link cache, and OpenPlugin to read back a plugin you just wrote.
Plugin Plugin.New(fileName, style, author, description, localized) makes a master plugin with the Creation Kit's header (Master plus Light or Medium flag, form version 582). IdRange(style) gives the FormIDs a style may use.
PluginWriter Write(mod, outDir, game, options) fills effect data, writes ONAM like the Creation Kit, takes master flags from the open masters, lists masters in load order and writes on one thread, so the same build gives the same bytes. See the options below.
Effects New(baseEffect, magnitude, area, duration) makes an effect entry. Fix(list) and FixAll(mod) fill a missing EFIF (0) and MUID (position + 1, never a duplicate). Without them, effects on spells, enchantments and ingestibles never apply in game.
Quests New(mod, editorId) makes a quest with empty (not missing) condition and alias lists, so it's written with NEXT and ANAM like a Creation Kit quest. A quest made with plain AddNew has neither.
DialogTopics FixSubtypeNames(mod) fills a blank SubtypeName (SNAM) on every dialogue topic with the code that matches its Subtype, as vanilla topics have. PluginWriter.Write calls it for you.
IdLock Apply(mod, lockPath) keeps every own record's FormID the same from build to build, using a JSON file of EditorID to FormID. New records get the next free ID. The build stops if a locked record disappears, if two records share an EditorID, or if a record has no EditorID. update: false only checks.
GameplayOptions Debug(...) makes a "Show Debug Messages" option, off by default, for Settings > Gameplay Options. Bool(...) makes other on/off options, and Group(...) makes the mod's own options group. Create the options first and the group last.
Localized Text(s) gives the same text in all nine languages the game ships, for localized plugins.

Write options

Option Default Meaning
OverriddenForms Iterate Fill the header's ONAM list like the Creation Kit. Mutagen 0.54.4's own default writes none, and the game then ignores a plugin's edits of temporary references in its masters' cells.
Deterministic true Write on one thread. With parallel writing, Mutagen 0.54.4 can number a localized plugin's strings differently on every run.
FixEffects true Run Effects.FixAll before writing.
FixDialogSubtypes true Run DialogTopics.FixSubtypeNames before writing. Topics that already have an SNAM are left alone.
MasterOrder open order The order masters are listed in the header.
Masters none An explicit master list, written exactly as given, even masters no record points into (for patches that list a master only to load after it).
MastersListContent Mutagen's Lower-level form of Masters: NoCheck writes the header's MasterReferences as you filled them.
NextFormId Mutagen's NoCheck keeps the Next Object ID you set in the header instead of recomputing it.
GapCheck true After writing, run mutagen-gap-check.py on the plugin if the script is found (see below).
GapCheckScript none Path to that script.
GapCheckMastersDir none Extra folder the gap check searches for masters.
FailOnGapErrors true Throw when the gap check reports an error.

The gap check

The gap check is an optional Python script that compares a written plugin with its masters and reports data Mutagen 0.54.4 is known to lose on write, plus missing ONAM entries. It isn't part of this package. BuildKit runs it when it finds mutagen-gap-check.py (from WriteOptions.GapCheckScript, the BUILDKIT_TOOLS environment variable, or a tools folder above the builder); otherwise it prints one "skipped" line and carries on.

Same bytes every build

A builder on BuildKit gives byte-identical output for the same inputs: one-thread writing fixes string numbering, and the ID lock fixes FormIDs. That makes it easy to prove a refactor changed nothing: build before and after, then compare the files.

Tests

dotnet test tests/BuildKit.Tests

The tests make every plugin they need in a temp folder. No game files are needed or included.

Privacy

BuildKit collects nothing and makes no network calls. See PRIVACY.md.

License

GPL-3.0 (see LICENSE), the same license as Mutagen. BuildKit doesn't include or need any Bethesda files; it reads the plugins in your own game install.

Product Compatible and additional computed target framework versions.
.NET net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.2.0 69 11/9/2026
0.1.0 60 11/9/2026