BG3 Load Order Optimizer

BG3 Load Order Optimizer is a Windows desktop app that helps Baldur's Gate 3 players understand their installed mods, preview an explainable load order, and apply approved changes with backups.

Current public release: v1.4.1 on GitHub

The v1.4.1 release was published on September 7, 2026. The GitHub tag, release, and published asset are immutable. The exact ZIP SHA-256 is recorded in the GitHub release notes and linked from RELEASES.md.

• Current public download: latest GitHub release
• Release verification: v1.4.1 release record
• Downloads and release notes: Nexus Mods
• Community sorting rules: BG3 Load Order Masterlist
• Announcements: Reddit u/Nemix_3D
• Support: Patreon or Buy Me a Coffee

What it helps with

• Finds your BG3 installation, Mods folder, and player profiles.
• Scans installed PAK files and compares them with your active load order.
• Highlights missing dependencies, duplicate mods, cycles, file overlaps, Stats conflicts, and other useful diagnostics.
• Offers Public Masterlist and BG3 Community Guide sorting options.
• Explains why each suggested move is being made before anything is applied.
• Creates backups before supported load-order changes and can restore recent versions.
• Includes Save Doctor, known-working-save comparison, and local Crash & Mod Health checks.
• Supports BG3 Mod Manager and Vortex workflows through Mod Update Mode.

A simple, safer workflow

1. Scan your installed mods and active profile.
2. Review warnings, dependencies, overlaps, and sorting guidance.
3. Choose Optimize to create a preview.
4. Check the proposed moves and their reasons.
5. Choose Apply Changes only when you are satisfied.

Scan and Optimize are preview-only. The app does not change your active load order until you confirm an action that requires a write, and supported profile changes create a backup first.

Download and install

1. Open the latest release.
2. Under Assets, download BG3-Load-Order-Optimizer-v1.4.1.zip.
3. Extract the entire ZIP into its own folder and keep the included files together.
4. Run BG3LoadOrderOptimizer.exe.

Version 1.4.1 is the published public release. The v1.4 work and its historical beta milestones are documented in the progress log and roadmap. See the changelog, security and privacy disclosure, and v1.2 release record.

The v1.3.0 section below is retained as historical release context. The current public package is v1.4.1.

v1.4.1 public release

The published Windows 10/11 x64 release carries forward the v1.4 feature set and hardens release-critical behavior:

• Online Community Masterlist updates require explicit opt-in. Offline Masterlist mode is supported, and Update Masterlist Now is a one-time explicit action. No automatic masterlist request is made before consent.
• Deactivate -> Apply -> rescan preserves the inactive state in the profile.
• Optimize reports a visible result for both moved and already-optimal orders.
• Protect Load Order is restored, with safe unlock, write, verify, and re-protect behavior.
• Timeout, cancellation, transaction, and race handling are hardened around scan, update, and profile operations.
• Save Doctor, .bg3nmx interchange, and privacy boundaries remain local, explicit, and path-scrubbed where sharing is requested.

The immutable release is available from the v1.4.1 GitHub release.

v1.4.0 historical release

The published Windows 10/11 x64 release includes portable .bg3nmx interchange, inactive .pak import, profile and settings usability improvements, bounded extensible sorting methods, and release-provenance evidence. The immutable release is available from the v1.4.0 GitHub release.

Independence disclaimer

BG3 Load Order Optimizer is an independent, community-developed third-party tool. It is not affiliated with, endorsed by, sponsored by, or officially connected to Larian Studios or Wizards of the Coast. Baldur's Gate 3 and related names are trademarks of their respective owners. See the full independence disclaimer.

The repository layout is documented in Project layout. Local release folders and archived build output are kept separate from source and are never included in the public ZIP automatically.

What is in 1.4.1

• Local crash and mod-health evidence review with privacy-scrubbed reports.
• Save Health analysis with expandable campaign groups, refreshable in-game thumbnails, full package-read verification, and recorded-mod comparison. Generated clean copies use a recognizable BG3 Load Order Optimizer banner until BG3 creates the next real screenshot.
• Known-working-save comparison for mod additions, removals, version changes, and relative-order changes.
• A separately named Experimental Clean Copy that can remove selected missing-mod metadata and repair invalid, duplicate, or malformed module rows after creating a verified backup.
• Persistent recovery history and verified rollback after restarting the application.
• Read-only Script Extender residue inspection plus a validated, version-specific cleanup-recipe framework. The shipped recipe catalog is intentionally empty; mod-owned Script Extender, Osiris, story, item, quest, and character state is not deleted automatically.
• Tabbed Options for File Paths, General behavior, and External Tools. Connected .exe applications appear directly in the Tools menu with their executable icon and filename and launch only when explicitly selected, without injected arguments or downloads.

What works in the public release

• Steam library, standard Mods directory, and player-profile discovery, with editable paths.
• In-process LSLib 1.20.4 PAK reading; no external executable is launched.
• Safe metadata extraction from LSX/LSF, including UUIDs, names, authors, versions, folders, and declared dependencies.
• Active, inactive, and missing-mod reconciliation against both legacy ModOrder profiles and current Patch 7/8 ordered Mods profiles.
• Duplicate UUID, missing dependency, self-dependency, and explicit cycle diagnostics.
• Internal resource indexing and file-overlap categories with current precedence/winner information.
• Explainable per-scan mod categorization from installed PAK contents and dependency metadata, with category confidence/source shown in the UI and an Uncategorized filter.
• Entry-level parsing of generated Stats text across different filenames, with semantic collision reporting.
• Script Extender Lua detection, exact-path overlap detection, and simple Ext.Require/require indexing. Lua is never executed.
• Local MCM integration detection: an installed MCM_blueprint.json creates a high-priority recommendation for Mod Configuration Menu to load before that consumer when both are active.
• Evidence-based research-draft-1-v2 shipped JSON masterlist plus a validated online overlay and separate local user rules. It contains 51 rule objects, 68 verified hard relationships, and soft foundational/late-loading group guidance. Declared package dependencies are always used.
• Conditional rules for installed-mod combinations, subject versions, Script Extender package use, and exact internal resources. Rule messages include source and recommended action.
• Transactional HTTPS masterlist updates with schema/cycle validation, a 10 MB limit, SHA-256 integrity state, atomic promotion, and a retained previous revision.
• Deterministic stable topological sorting that enforces hard dependencies first, applies explicit masterlist recommendations before guide fallback placement, preserves unknown relative order, and explains moves or skipped soft recommendations.
• Dry-run Optimize preview. No BG3 file changes occur until Apply Changes is confirmed.
• A plain-language Resolve Issues workflow removes stale load-order entries for missing PAK files after creating a backup, while leaving dependencies, duplicates, damaged packages, and incompatibility choices to the user.
• Timestamped backups, structurally validated temporary output, replacement, re-read verification, and automatic rollback on export failure. Existing descriptor fields such as MD5, PublishHandle, and game-generated attributes are preserved.
• Persistent size/timestamp-aware scan cache, bounded parallel scans, progress, and cancellation.
• Search and active/inactive/unknown-placement/warning/conflict/missing filters, per-mod sorting-basis details, sourced diagnostics, and a current-versus-preview move table with rule provenance.
• Side-by-side controls for enabling or disabling the BG3 Script Extender debug console while preserving every unrelated Script Extender setting.

The v1.4.1 download is self-contained for Windows 10/11 x64, so no separate .NET installation is required. It is portable and does not include an uninstaller; close the app and delete its extracted folder to remove it. This does not remove BG3 mods or your load order.

Privacy and safety

• The app works locally and does not inject into BG3 or modify game memory.
• It does not request administrator privileges, collect credentials, include telemetry, or upload reports automatically.
• Save and crash reports are copied or saved only when you choose.
• Check for Updates can open the official Nexus Mods page after confirmation; it does not download or run updates.
• The official release is not digitally signed yet, so some antivirus products may show a false positive.

Read the full security and privacy information and antivirus guidance.

Important limits

The shipped v2 list gives verified foundational frameworks a soft early-loading preference and gives Compatibility Framework a soft late-loading preference. These relationships are evaluated before local package heuristics, while declared dependencies and explicit hard author rules always win. A generic category recommendation does not displace an unknown or weakly classified mod merely because it has a numerically later guide rank.

On every scan, the app assigns a broad content category from installed PAK resources and separates category confidence from guide-placement confidence. Verified identities and clearly dominant package evidence can participate in a compact community-guide soft ordering: ImpUI (ImprovedUI) first; early libraries/frameworks; items, spells, actions, fixes and gameplay; feats/races/classes/subclasses; the guide's preferred UI sequence; the guide's appearance sequence; then confirmed integrations and Compatibility Framework late. Weak or unknown placement evidence is excluded from that guide sequence, so the player's existing relative order remains the fallback. Exact MCM_blueprint.json and CompatibilityFrameworkConfig.json resources create explainable integration recommendations without parsing or executing those files. Ordinary patches are ordered by their declared dependencies and are not sent to the global bottom from a name alone. Verified masterlist relations are evaluated ahead of guide fallback placement. Declared package dependencies and verified hard rules remain mandatory; contradictory hard evidence blocks Apply instead of being silently ignored. A right-click Move selected to... action accepts an exact zero-based position and creates the same reversible manual preview as Move Up/Down.

No load-order tool can guarantee perfect compatibility for every mod setup. Some conflicts require a compatibility patch or a choice between mod behaviors. BG3 Load Order Optimizer reports evidence and uncertainty instead of guessing.

BG3 Load Order Optimizer does not merge resources or generate compatibility patches. Binary Root Templates, VisualResources, AnimationSets, VFX, localization, and Osiris story data are currently compared at the file level. Generated Stats .txt data receives entry-level analysis.

Always follow current instructions from mod authors when they conflict with general sorting guidance.

Diagnostic and launch safety

Save Doctor analysis remains read-only. An Experimental Clean Copy is separately named and branded, created only after a byte-verified backup, and limited to selected module-list rows plus invalid, duplicate, or malformed module metadata. Revert verifies that the untouched original still matches its backup before offering to remove only the generated copy. Unsupported packages are reported and left unchanged; the tool does not claim to repair arbitrary story, quest, item, character, Osiris, or Script Extender state.

Crash & Mod Health Check reads only a small allow-listed set of recent local BG3, Script Extender, Native Mod Loader, and Osiris logs. Log input is bounded, findings retain evidence and confidence labels, and a mod mention is a lead rather than proof of causation. Nothing is uploaded. A shareable report is created only when the user chooses Copy Shareable Report, and Windows user-profile paths are replaced with <UserProfile> throughout that copied text.

Launch Game uses the configured BG3 executable without adding launch arguments, refuses a second launch while BG3 is already running or a prior launch is still tracked, and releases its process-tracking handle when the optimizer closes without terminating BG3. The Script Extender Debug Console controls require Norbyte Script Extender's expected bin\DWrite.dll; settings changes preserve unrelated JSON fields and use verified replacement with recovery of an existing settings file if final verification fails.

Help and community

• Report a bug
• Request a feature
• BG3 Load Order Masterlist
• Reddit announcements
• Patreon · Buy Me a Coffee

Contributing

You can help by reporting reproducible bugs, suggesting improvements, or providing direct mod-author evidence for the BG3 Load Order Masterlist. Include clear reproduction steps, mod UUIDs, and source links when they are relevant.

The public v1.4.1 portable package does not include an uninstaller. Delete the extracted app folder manually after closing the application; it does not remove BG3 mods or modsettings.lsx.

Code and documentation contributions require prior permission. This repository is source-visible, not open source, and the personal-use license does not grant permission to modify or redistribute Nemix-authored material. Before preparing a patch or pull request, open an issue or contact nemix3d@gmail.com to agree on the scope and permission.

For approved code work:

• Use Windows with the .NET 8 SDK.
• Read the architecture overview and, for sorting rules, the rule format.
• Keep changes focused and include tests when behavior changes.
• Do not modify release assets or published packages unless the work is specifically part of an authorized release.

Usage

On the first launch, the setup wizard explains the three locations BG3 Load Order Optimizer uses: the optional BG3 installation folder, the Mods folder, and the PlayerProfiles folder containing modsettings.lsx (usually the Public profile). Auto-detect BG3 paths checks Steam libraries and the standard Larian AppData folders; each path can also be browsed to manually. After setup, BG3 Load Order Optimizer offers a short annotated tutorial with arrows showing Scan, analysis, Optimize preview, backup, and Apply.

1. BG3 Load Order Optimizer detects Steam libraries, %LOCALAPPDATA%\Larian Studios\Baldur's Gate 3\Mods, and player profiles.
2. Correct the displayed Mods path if needed and use Options > Settings.
3. Use Scan. Use Force Rescan only when bypassing the cache is useful.
4. Inspect dependency, file, Stats, and Script Extender diagnostics.
5. If Resolve Issues is enabled, use it to clean missing-PAK references or get clear instructions for issues that cannot be safely automated.
6. Use Optimize and review every Before → After row and its reason.
7. Use Apply Changes only after resolving high/critical diagnostics. BG3 Load Order Optimizer backs up and verifies automatically.
8. Use File > Save Load Order to create a portable .bg3nmx document or File > Load Load Order to validate and preview one. Neither action changes BG3 files.
9. File > Recent Versions restores a selected backup after first backing up the current file.
10. Select one or more rows, then use a checkbox or right-click action to activate or deactivate every selected mod in one validated preview. Delete mod / remove missing entry handles the full selection too: installed PAKs go to the Recycle Bin, while missing rows only remove stale active-order references after a verified backup. A missing row cannot be activated because no package exists.

Before Apply, the optimizer rechecks that the selected profile, its modsettings.lsx, the top-level PAK inventory, local rules, masterlist files and provenance, category/sorting overrides, and sorting method identity/configuration are the same inputs used to create the preview. Manual row moves and activation changes are part of that preview state. If anything changed, Apply stops before writing, names the changed inputs, discards the stale preview, and asks you to Scan and Optimize again.

Sort with includes Masterlist (Recommended), BG3 Community Guide, and a clearly labeled Experimental (experimental-v1) strategy. Experimental is testing-only and shows a warning; its initial broad fallback order is the accepted guide hierarchy. You can create bounded custom methods that reorder the existing broad fallback buckets without scripts, expressions, or plugins. Hard package dependencies, verified masterlist relationships, and explicit hard local rules always override a fallback method. Custom methods are stored under the local application settings root, and changing or editing one invalidates an existing preview.

Edit > Rules opens a simple form for choosing which mod loads first. Advanced users can see Rule format. Help > Report Bug opens a private local form that can save or copy a report; it never uploads automatically. Contact Me, masterlist contributions, and supporter links are also grouped under Help. The setup and tutorial windows include thank-you links for supporters: Patreon @nemix_3d and Buy Me a Coffee.

Security and reporting

The application works locally and does not inject into BG3, modify game memory, request administrator privileges, upload diagnostics automatically, or collect credentials. See the security and antivirus information for the release behavior and current false-positive status.

Use the bug report template for reproducible tool problems and the feature request template for improvements. For incorrect sorting, include the mod UUID, author instructions or dependencies when available, and whether you used Masterlist or Community Guide sorting.

Backups and troubleshooting

Backups are never collapsed into one file. Each BG3 profile has its own folder under %LOCALAPPDATA%\Nemix\BG3LoadOptimizer\Backups. Logs are structured JSON Lines under %LOCALAPPDATA%\Nemix\BG3LoadOptimizer\Logs.

If a scan reports PAK_SCAN_FAILED, the individual package is malformed, unsupported, or unreadable; other packages continue scanning. If Apply is disabled, resolve the high/critical diagnostics first. If BG3 later resets modsettings.lsx, inspect the game's mod errors and verify required campaign/game modules—the optimizer preserves unknown game-generated XML instead of reconstructing the complete file.

Build from source

dotnet restore Nemix.BG3LoadOptimizer.sln
dotnet build Nemix.BG3LoadOptimizer.sln -c Release -p:Platform=x64
dotnet test tests\Nemix.BG3LoadOptimizer.Tests\Nemix.BG3LoadOptimizer.Tests.csproj -c Release
$outputRoot = Join-Path ([IO.Path]::GetTempPath()) 'BG3LoadOrderOptimizer-source-build'
dotnet publish src\Nemix.BG3LoadOptimizer.App\Nemix.BG3LoadOptimizer.App.csproj -c Release -r win-x64 --self-contained true -o $outputRoot

Use a disposable output path for a source build. Do not publish directly into Beta Build, Public Version, archive, or an existing release archive. Developer Build is replaceable generated output, not a public-release source. The release manifest/package validator must pass against a reviewed candidate before a later explicit packaging operation.

Release publishing automatically removes the unused .NET native debugger and dump-collection payload (createdump, DAC/DBI, and DIA Symbol Reader binaries). The application does not invoke those components; its local crash reports are implemented in managed code. The portable release remains self-contained.

Source and license

This repository is source-visible so players and reviewers can inspect how the app works. It is not open source. The personal-use license permits use of an official unmodified release but does not grant rights to redistribute, modify, reuse, or claim Nemix-authored material.

The v1.4.1 release includes release-provenance.json. It records the package version, assembly identity, source revision state, shipped masterlist release/revision/hash, and a deterministic relative-path inventory. The inventory and SHA-256 values provide integrity evidence only; they do not authenticate the publisher. Absolute developer paths, credentials, and source files are not included. The historical public v1.3.0 package predates this manifest.

For future public releases, upload only BG3-Load-Order-Optimizer-vX.Y.Z.zip as a custom GitHub asset. Put its SHA-256 in the release notes; retain checksum and provenance files as internal validation evidence rather than separate public assets.

For future release candidates, the same gate rejects source/project files, debug symbols, scripts, logs, temporary files, nested archives, uninstaller or native debugger payloads, personal paths, credential-like text, and stale provenance inventory. The manifest is a release inventory, not an SBOM, and its hashes provide integrity evidence only.

Licensing and acknowledgements

BG3 Load Order Optimizer is distributed under the proprietary BG3 Load Order Optimizer Personal Use License: it is free to use, but no rights are granted to redistribute, sell, modify, remake, reuse, or claim creator-authored material. This is a source-visible repository, not an open-source license. LSLib is bundled under its MIT license; see Third-party notices. Baldur's Gate 3 and related names are trademarks of their respective owners. This project is not affiliated with or endorsed by Larian Studios.