wabbajack/NexusPage.html

<h2 id="wabbajackanautomatedmodlistinstallerfortesfalloutgames">Wabbajack - An automated modlist installer for TES/Fallout games</h2>

<p><a href="https://dev.azure.com/tbaldridge/tbaldridge/_build/latest?definitionId=1&amp;branchName=master"><img src="https://dev.azure.com/tbaldridge/tbaldridge/_apis/build/status/halgari.wabbajack?branchName=master" alt="Build Status" /></a></p>

<p>
    The general idea behind this program is fairly simple. Given a Mod Organizer 2 folder and profile, generate list of instructions that will allow
    a program to automatically recreate the contents of the folder on another machine. Think of it as replication, but without ever distributing copyrighted
    files or syncing data between the source and destination machine. The end result is a program that recreate a modlist on a computer while respecting the
    rights of the game publisher and the mod authors.
</p>

<h3 id="installingamodlist">Installing a Modlist</h3>

<p>Please visit our Discord link below for information on how to obtain and install a modlist. </p>

<h3 id="sociallinks">Social Links</h3>

<ul>
    <li><a href="https://discord.gg/zgbrkmA">Discord</a></li>

    <li><a href="https://www.patreon.com/user?u=11907933">Patreon</a> Check this page for updates and to vote on features</li>
</ul>

<h3 id="whatwabbajackcando">What Wabbajack can do</h3>

<p>
    At this point you may be wondering how much of a complex modlist Wabbajack can handle. At this point it's more about what Wabbajack <em>can't</em> handle, but
    let's do a rundown of all the supported features:
</p>

<ul>
    <li>
        Support for the following games is tested on a regular basis


        <ul>
            <li>Fallout 4</li>

            <li>Fallout New Vegas</li>

            <li>Skyrim SE</li>

            <li>Skyrim LE</li>
        </ul>
    </li>

    <li>
        Support for automatic downloads from the following sources


        <ul>
            <li>Nexus Mods (Premium accounts only)</li>

            <li>Dropbox</li>

            <li>Google Drive</li>

            <li>Mega</li>

            <li>ModDB</li>

            <li>Direct URLs (with custom header support)</li>
        </ul>
    </li>

    <li>
        Support the following archive types


        <ul>
            <li><code>.zip</code></li>

            <li><code>.7z</code></li>

            <li><code>.rar</code></li>

            <li><code>.fomod</code> (FNV archives)</li>
        </ul>
    </li>

    <li>
        The following mod installation types are supported


        <ul>
            <li>Files installed with our without fomod installers</li>

            <li>Files from <code>.omod</code> mods like <code>DarNified UI</code> or <code>DarkUId Darn</code></li>

            <li>Manually installed mods</li>

            <li>Renamed/deleted/moved files are detected and handled</li>

            <li>Multiple mods installed into the same mod folder</li>

            <li>A mod split across multiple mod folders</li>

            <li>Any tools installed in the MO2 folder. Want your users to have BethIni or xEdit? Just put them in a folder inside the MO2 install folder</li>

            <li>ENBseries files that exist in the game folder</li>

            <li>SKSE install</li>
        </ul>
    </li>

    <li>
        The following situations are automatically detected and handled by the automated binary patcher (not an exhaustive list)


        <ul>
            <li>ESP cleaning</li>

            <li>form 44 conversion</li>

            <li>ESP to ESL conversion</li>

            <li>Adding masters</li>

            <li>Dummy ESPs created by CAO</li>

            <li>(really any ESP modifications are handled)</li>

            <li>Mesh fixing</li>

            <li>
                Texture compression / fixing
                The following BSA operations are detected by extracting or creating BSAs via Wabbajack's custom BSA routines
            </li>

            <li>BSA Unpacking</li>

            <li>BSA Creation (packing loose files)</li>

            <li>BSA repacking (unpacking, fixing files and repacking)</li>
        </ul>
    </li>
</ul>

<p>That being said, there are some cases where we would need to do a bit more work to develop:</p>

<ul>
    <li>Manually downloaded files</li>

    <li>LL Files (currently no plans to implement)</li>

    <li>esp to esm conversion (there are hacks for this)</li>

    <li>binary patching of non-bsa huge files. 256MB is the largest size Wabbajack can currently handle with the binary patcher</li>
</ul>

<h3 id="thewabbajackpermissionssystem">The Wabbajack Permissions System</h3>

<p>
    While Wabbajack can perform a large variety of operations on mod files, we recognize that some authors don't want to deal with
    the support requests that come from some users performing operations on these files. Therefore we worked together with several
    authors to create a permissions system Wabbajack will follow during installation and creation of a modlist. This permissions file
    can be found on <a href="https://github.com/wabbajack-tools/opt-out-lists/blob/master/NexusModPermissions.yml">Github</a>. Feel free to contact
    us via discord about any questions you may have.
</p>

<h3 id="creatingamodlistinstaller">Creating a ModList Installer</h3>

<p>Overview video <a href="https://www.youtube.com/watch?v=5Fwr0Chtcuc"><code>https://www.youtube.com/watch?v=5Fwr0Chtcuc</code></a></p>

<p>
    1) Download Wabbajack and install it somewhere outside of your normal Mod Organizer 2 folder
    (otherwise Wabbajack will try to figure out how to install itself and that might cause a collapse in the time-space
    continuum).
    2) Make sure every archive you used in your MO2 profile has some sort of download information attached.
</p>

<ul>
    <li>If the file was downloaded via MO2 you're good, no extra work is needed</li>

    <li>If the file was downloaded manually from the Nexus, copy it into the MO2 downloads folder, go back to MO2</li>

    <li>
        and go to the <code>downloads</code> tab. Find the file and click <code>Query Info</code> from the right-click menu. MO2 should find
        the download info for you
    </li>

    <li>For other files (ENBSeries, SKSE, SRO, etc.) Look at the [<code>RECIPES.md</code>] file</li>

    <li>
        for instructions specific to your file source.
        3) Now load Wabbajack, and point it to the <code>\&lt;MO2 Folder&gt;\mods\&lt;your profile&gt;\modlist.txt</code> file.
        4) Click <code>Begin</code>.
        5) Wabbajack will start by indexing all your downloaded archives. This will take some time on most machines as the application
        has to performa <code>SHA-256</code> hash on every file in every archive. However the results of this operation are cached, so you'll only need
        to do this once for every downloaded file.
        6) Once completed, Wabbajack will collect the files required for the modlist install and begin running them through the compilation stack.
        7) If all goes well, you should see a new <code>&lt;your profile name&gt;.exe</code> file next to <code>Wabbajack.exe</code> that you just ran. This new <code>.exe</code> is the one
        you want to hand out as a auto modlist installer.
    </li>
</ul>

<h3 id="installingamodlist-1">Installing a ModList</h3>

<p>
    1) Get a modlist installer, it's a <code>.exe</code> file that was created by Wabbajack
    2) Run the <code>.exe</code>, the install folder defaults to the same folder as the executable, change it if you want.
    3) Click <code>Begin</code> to start installation. At some point you will be prompted for SSO authorization on the Nexus, files
    will be auto installed and downloaded
    4) After installation has completed, run <code>Mod Organizer 2.exe</code>, select <code>Portable</code> and your game type.
</p>

<h3 id="howitworks">How it works</h3>

<p>At a technical level the process is as follows.</p>

<p>
    1) Hash and cache the contents of every archive in the <code>\downloads</code> folder. This lets Wabbajack know of all the possible locations where you could have installed mods
    2) Apply the <code>resolution stack</code> to every file in both the game's root folder and in the MO2 folder.
    3) Take the install directives and required archives and write their metadata to a JSON file.
    4) Attach the JSON file to Wabbajack itself, creating a new Auto-installer for the profile
</p>

<h3 id="theresolutionstack">The Resolution Stack</h3>

<p>Every file analyzed by Wabbajack is passed through a stack of rules. The first rule to match the file creates a <code>Install Directive</code> or a instruction on how to install that specific file.</p>

<p>Currently the Resolution stack looks like this:</p>

<p>
    1) Ignore the contents of <code>logs\</code>
    2) Directly include .meta files int the <code>downloads\</code> folder
    3) Ignore the contents of <code>downloads\</code>
    4) Ignore the contents of <code>webcache\</code>
    5) Ignore the contents of <code>overwrite\</code>
    6) Ignore any files with <code>temporary_logs</code> as a folder in the path
    7) Ignore <code>.pyc</code> files
    8) Ignore <code>.log</code> files
    9) Ignore any files in <code>profiles</code> that are not for the selected MO2 profile
    10) Ignore any disabled mods
    11) Include any profile settings for the selected profile by including them directly in the modlist
    12) Ignore "ModOrganizer.ini", it will be re-created when MO2 starts on the new machine
    13) Ignore "Data" in the Game directly (in your Steam folder)
    14) Ignore "Papyrus Compiler" in the game folder
    15) Ignore the "Skyrim" folder in the game folder
    16) Ignore any BSAs in the game folder
    17) Include all meta.ini files from all (selected) mods
    18) Include archive and file meta information for any file that matches a file in an archive directly via a SHA256 comparison
    19) Rip apart any <code>.bsa</code> files and run a mini resolution stack on the contents to figure out how to build the .bsa from the input files
    20) Generate patches for files that may have been modified after being installed from an archive (see section on Patching for more info)
    21) Include dummy ESPs directly into the modlist
    22) Ignore files in the game directory
    23) Ignore .ini files
    24) Ignore .html files (normally these are logs)
    25) Ignore .txt files
    26) Ignore <code>HavockBehaviourPostProcess.exe</code> this seems to get copied around by tools for some reason
    27) Ignore <code>splash.png</code> it's created for some games (like FO4) by MO2
    28) Error for any file that survives to this point.
</p>

<p>So as you can see we handle a lot of possible install situations. See the section on <a href="README.md#Creating_a_ModList_Installer"><code>Creating a Modpack</code></a> for information on working with the installer</p>

<h3 id="wabbajackflags">Wabbajack Flags</h3>

<p>The if the following words are found in a mod's notes or comments they trigger special behavior in Wabbajack.</p>

<ul>
    <li><code>WABBAJACK_INCLUDE</code> - All the files int he mod will be inlined into the installer</li>

    <li><code>WABBAJAC_ALWAYS_ENABLE</code> - The mod's files will be considered by the compiler even if the mod is disabled in the profile</li>
</ul>

<h3 id="patches">Patches</h3>

<p>
    Wabbajack can create binary patches for files that have been modified after installation. This could be <code>.esp</code> files that have been cleaned or patched. Or
    it could be meshes and textures that have been optimized to work better in a given game. In any case a BSDiff file is generated. The output of this process
    is copied directly into the modlist instructions. However! It is important to note that the patch file is 100% useless without the source file. So <code>original + patch = final_file</code>. Without the original file, the final file cannot be recrated. This allows us to distribute arbitrary changes without violating copyrights as we do not copy
    copyrighted material. Instead we copy instructions on how to modify the copyrighted material.
</p>

<h3 id="faq">FAQ</h3>

<p><strong>How do I get Wabbjack to handle mods from <code>X</code></strong></p>