theposhwolf/modrify

PowerShell module for working with Bethesda mods

Modrify

Powered by Mutagen.

Modrify is a PowerShell module with the goals of:

• Make mod reading, editing, overriding (etc) easily accessible at the commandline
• Expose Mutagen's functionality in PowerShell
• Providing the same or similar features as whats available using Pascal in xEdit
• Create patcher scripts, similar in results to Synthesis, but in PowerShell

This is not intended to compete with or slight xEdit or Synthesis. This is written purely out of my desire to work in PowerShell.

I started this module after stumbling across the Mutagen .NET library. I have a strong preference for PowerShell over Pascal, so I was very excited to finally have a way to script Bethesda mods with PowerShell. My professional interests tend to bleed over into my personal interests, so of course I enjoy automation in the Bethesda games that I play.

As I have time to work with this module to convert some of the xEdit Pascal scripts and write some of my own, expect better examples and more robust code. If you have an issue, question, or wonder how to do a certain thing with this module, please feel free to open up an issue.

Installation

Modrify, and its submodules, require PowerShell 7.3+ and will not work in any earlier version of PowerShell (7.2-) or Windows PowerShell (PowerShell 5.1-). You can test your PowerShell version with:

$PSVersionTable

Modrify, and its submodules, are available in the PowerShell Gallery, so they can be installed with:

Install-Module Modrify

Since module dependency has been configured, if you install a submodule, it will automatically install the root module as well.

The current list of submodules:

• Modrify.Skyrim
• Modrify.Fallout4

This list is based on support by the underlying library (Mutagen) as well as implementation here into this module. If you don't see a specific Bethesda game in this list, check Mutagen first. If Mutagen supports it, open an issue here and I will look at implementation.

Usage

Setup

Start by setting your game environment, so Modrify knows where to look:

Set-ModrifyGame -Release SkyrimSE

Once you've set the game environment, you will be able to use the other commands in each module.

Getting data

Modrify is able to retrieve data about your load order or specific mods very well. For example, if you'd like to build a spreadsheet of all people NPCs with their name, race, and factions, you can do so with:

# Get the game environment to capture the LinkCache object
$ge = Set-ModrifyGame SkyrimSE -Passthru
# List out the races
$raceStrings = 'ArgonianRace','BretonRace','DarkElfRace','ElderRace','HighElfRace','ImperialRace','KhajiitRace','NordRace','OrcRace','RedguardRace'
$races = Get-SkyrimWinningOverrides -RecordType Race | ?{$raceStrings -contains $_.EditorID}
# Get the NPCs with those races
$npcs = Get-SkyrimWinningOverrides -RecordType Npc | ?{$races -contains $_.Race}
# Build the output object and export to an Excel spreadsheet
$npcs | %{
    [pscustomobject]@{
        Name = $_.Name.String
        Race = $_.Race.TryResolve($ge.LinkCache).Name.String
        Factions = ($_.Factions.Faction | %{$_.TryResolve($ge.LinkCache).EditorID}) -join ', '
    }
} | Export-Excel .\SkyrimPeople.xlsx -TableName Npcs -Autosize

This may throw errors trying to resolve factions, I'm not yet sure why. It still works.

This example depends on the ImportExcel module for the Export-Excel function.

If you wanted to run that report on a specific mod, you can switch out Get-SkyrimWinningOverrides for Get-SkyrimMajorRecords and specify a mod by path or ModKey.

Creating patches

This module can be used for creating patches. For example, if you needed to add a specific keyword to some armors:

$ge = Set-ModrifyGame SkyrimSE -Passthru
# Create a new light (ESL) mod in memory
$newMod = New-SkyrimMod -ModKey 'MyPatch.esp' -HeaderFlags LightMaster
# Get the keyword to add
$keyword = Get-SkyrimMajorRecords -ModKey 'Skyrim.esm' -RecordType Keyword | ?{$_.EditorID -eq 'ArmorClothing'}
# Get the armors to add keywords to and copy them as override to the new mod
# You could filter for specific armors using Where-Object (?)
$armors = Get-SkyrimMajorRecords -ModKey 'Skyrim.esm' -RecordType Armor | Copy-SkyrimRecordAsOverride -Mod $newmod
# Add the keyword
$armors | Add-SkyrimKeyword $keyword
# Write the patch to disk
Write-SkyrimMod $newMod -Path "$($ge.DataFolderPath)\$($newMod.ModKey)"

Contributing

The easiest way to contribute is to submit issues and provide detailed information about the bug or suggestion that you have.

If you are the coding type, please feel free to fork, commit changes, and submit a PR.

Building Modrify

Building Modrify requires .NET 7 and PowerShell 7.3+ with the following PowerShell modules:

• InvokeBuild
• PlatyPS
• EZOut

All other dependencies should be automatically resolved.

In the root of the repository, run:

Invoke-Build -Task ModuleBuild

This will invoke the build script which will clean up the build folder (if it exists), run a dotnet clean -> restore -> publish, build the PowerShell manifest, and then collect all the required files into the ./build folder, sorting into module sub folders. Once complete, you should be able to import any one of the modules with:

Import-Module .\build\Modrify
Import-Module .\build\Modrify.Skyrim

modrify's Issues

Module only works in PS 7.3

Looks like with the built in dependencies, the module only works with PowerShell 7.3.x. I'm not yet certain how to solve this, but I'll be leaning on the info in this post for help: https://devblogs.microsoft.com/powershell/resolving-powershell-module-assembly-dependency-conflicts/

Add a pipeline

All of the actions are in the build script, just need to get them in a pipeline.

New-*Mod should allow setting the mod header flag

Like making the mod light, a master, etc.

Add documentation

Add cmdlet documentation and a more thorough README with examples.

Write-*Mod should assume the DataFolderPath

If no path is included, Write-*Mod should assume that the full path is the selected game environment's DataFolderPath with the Mod's ModKey as the filename.

Implement ModContexts

Currently only OverrideMixIns.WinningOverrides has been implemented. OverrideMixIns.WinningOverridesContexts should be implemented as well as a separate cmdlet.