Yet Another BG3 Native Mod Loader (2024)

Yet Another BG3 Native Mod Loader

This is a dll plugin mod loader for Baldur's Gate 3

It comes in 2 types:

• A "watcher" tool which sits silently in the background waiting for the game to launch, and once it does, patches the game process.
• A one time use "injector" tool which watches for (10 seconds) a new game or existing game process and patches that. (For those who don't want a program continuously running in the background)
  

The main features of this mod loader are:

• No manual installation necessary!
• It does not modify any game files or touch the installation directory
  
  • Because it does not modify/replace/add files in the game directory, there is 0 maintenance required
  • 0 maintenance means, when you update the game, there is nothing to fix, the mod loader always works
  • You can keep all your game files pristine and untouched
    
• It is completely compatible with anyNativeModLoaderplugins
  
  • This means you can develop your plugin usingmyRust Native Plugin TemplateorNativeModLoader's BG3 Plugin Template.
    
• Compatible with Steam and GoG
• Stores your plugins in the larian local data folder alongside the mod folder
• Does not install anything. Deleting the tool is the same as "uninstalling"
  

This tool only supports Windows. It mightwork on WINE if you run the Windows game under it, but this is currently untested; whether it works or not is unknown. If you can verify the details about this, please let me know so I can update the status.

Source Code:https://github.com/MolotovCherry/Yet-Another-BG3-Native-Mod-Loader

Getting started
Manual

• Download the latest release
• Place the watcher.exeandinjector.exefiles wherever you want, maybe create shortcuts to them even.
  

Vortex
Mod Manager installation is not required for the tools to properly function. It is only provided for ease of installation. The files are self contained and can be placed and used from anywhere you wish.

• Download via "mod manager download" button
• Install with "engine injector" mod type
  

, run either one of the tools (which one does not matter);you'll get a finish setup message the first time, read it and follow the instructions.

Watcher

• Start the watcher tool. It will stay open in the background and keep patching the game when it loads*
• Run the game as you normally would
• Whenever you want to stop using this tool, go to your systray, right click on the mod loader icon, and click "Quit"
  

Injector

• Run the injector tool once within 10 seconds before you start the game
• Run the game as you normally would*
• Tool will close once successful (or timeout after 10 seconds if it can't find the process)
  

It is allowed to run the injector tool after the game process has already started, however you should do this before you load your actual save game, and you should note that plugins generally expect to be loaded on game startup. If they aren't, it is possible they may not work correctly. So it is preferable to start the tool right before you start the game to prevent problems

Important: this goes without saying, but you should not have NativeModLoader installed if you use these tools, as they will conflict with each other.

* If the tool doesn't detect the game, even though you have the right

, it is possible you may need to run the tool as admin. In most cases this shouldn't be required, but in rare cases the tool may not have permissions to see the game process unless you run it as admin.

Config options
install_root - The game's root installation directory, e.g.

(note: no trailing slash! this is important, please leave the trailing slash out). It is not required to configure this if your tools are placed in <bg3_root>/binor<bg3_root>/bin/subfolder. Do note that if bg3.exe andbg3_dx11.exeis found in dir paths . or .., it will override any set install_rootvalue
disabled - An array of plugins to disable. Each entry is the plugins filename without extension, e.g. `FooBar.dll` should have an entry named `FooBar`

Installing plugins
Any plugins and files that you'd normally place in
C:\Program Files (x86)\Steam\steamapps\common\Baldurs Gate 3\bin\NativeMods
Should be placed instead in
%LocalAppData%\Larian Studios\Baldur's Gate 3\Plugins

Some plugins mod game dlls themselves. If a plugin modded a game dll, the modded dll must be installed according to their instructions - in the game's bin directory and replacing the game dll with theirs. This is because a modded game dll is not a plugin, and the game itself uses/requires it. This of course only applies to the modded dll itself. Their plugin will of course work normally according to the plugin installation instructions above

Please note that many native dll plugins are not yet aware of this new path and might try to read and/or save configs/logs to<game_dir>\bin\NativeMods, which - if you saved/edited the plugin config from the plugin folder - will cause the plugin to not see your changes since it's reading a different file from a different path. A quick temporary solution is to symlink <game_dir>\bin\NativeModsto%LocalAppData%\Larian Studios\Baldur's Gate 3\Pluginsso they both point to the same config file.You might want to contact the respective plugin devs and tell them they need to fix that. That's an oversight on the plugin's side, as they shouldn't be reading their config from absolute paths.(see the FAQ if you need help knowing how to make a symlink)

Making plugins
You can usemyRust Native Plugin TemplateorNativeModLoader'sBG3 Plugin Template. What you use doesn't really matter much, just as long as it's a dll with a DllMain that does its hooking at runtime.

Support
If you need help with something, you can post comment in the comment section, or join my discord serverand ask for help there (#yet-another-bg3-mod-loader channel under Support category)

FAQ
I got a smartscreen warning, how do I remove it?
If the files are not widely distributed yet, you may also receive a SmartScreenpopup on windows when you run it. You can remove it by followingthese instructions.

Can I have native mod loader installed?
Please don't use this mod loader when the other one is installed. That could load dll plugins twice (if you have them in both places), when they're only supposed to be loaded once. I have no idea what would happen.

Dll plugins could be dangerous
Dll plugins run executable code. This loader will run *any* dll, regardless whether it's a plugin or was made for this game or not.Make sure you trust whatever plugins you are running!

Why this tool instead of Native Mod Loader?
Native Mod Loader modifies core game files. The game was designed to work with vanilla game files. If core DLL game files are modified, it may cause weird, undesirable, "random" problems which cannot be predicted. (I've seen a lot of bug reports).

The main reason I made this tool was because seeing that honestly scared me a bit, and I didn't want to gamble with my game. I wanted something safe and easy that just works.

Therefore, this mod loader modifies no game files at all! It is safer to use, and has none of those strange bugs, while achieving the exact same end result. Not only is it safer, but because it modifies 0 core game files, you will never have to replace any game DLL's when you update your game!

There's also another happy side effect of this design. It's easier,faster, and just works with minimal setup required!

Cleaner = better 😁

Do the tools work when the game updates?
Game updates will not break this tool. This tool will always be compatible with the game based on the way it was designed. However, the plugins you have may require an update in order to function properly again. Please check each respective authors plugin page for updates if their plugin stops working.

You use the word "patch" when talking about this? Patching is permanent isn't it?
I'm using the word "patch" when referring to the game instance in order to keep the terms as simple to understand as possible. The game instance is only patched in memory. No core files are ever modified. This means, when you start the game again without the tools, it's the same vanilla game installation that you've always had. In other words, the word "patch" describes a game instance you already injected plugins into.

How do I disable plugins?
To disable the native dll plugins, you can:

• Move the files out of the plugins folder (or put them in a subfolder. just not directly in the plugins folder)
• add the plugin name to the disabled field in the config (%LocalAppData%\Larian Studios\Baldur's Gate 3\Plugins\config.toml)
  
  • It looks like this `disabled = []`
  • For example, for a dll plugin named "FooBar.dll" in that folder, add the filename minus the extension to the array
  • It would look like this: `disabled = ["FooBar"]`
  • You can add as many as you want: `disabled = ["FooBar", "Bar", "Baz"]`
    
• If you're using the watcher tool, quit it. Or, don't open the injector. If no tool is running, the game process will not be patched
  

How do I uninstall?
This program does not install itself. To "uninstall" it, simply delete the tools you downloaded.

Is this compatible with NativeModLoader plugins
100% compatible! Just as long as the mod doesn't rely on any NativeModLoader specific behavior (if so, file an issue with the plugin author!)

Please note that many native dll plugins are not yet aware of this new path and might try to read and/or save configs/logs to<game_dir>\bin\NativeMods\.A quick temporary solution is to symlink<game_dir>\bin\NativeMods\to your local Plugins folder

My path has a single/double quote in it, what do I do?
Ordinarily you can use a regular path with a literal string in toml like so
install_root = 'C:\Program Files (x86)\Steam\steamapps\common\Baldurs Gate 3'But if you have a single quote in your path, it's not possible to parse a string with 3 single quotes, since there's no way for the program to know where the beginning and end of the string is.

Instead, use double quotes like so:
install_root = "C:\\Program Files (x86)\\Steam\\steamapps\\common\\Baldur's Gate 3"Note here that all \in the source string now need to be escaped with an additional \. If you have a double quote anywhere in the path, also escape it with a \ like so
install_root = "C:\\Program Files (x86)\\Steam\\steamapps\\common\\Baldur's \"Gate\" 3"

The tool files keep disappearing!
That's definitely not normal!

The tools don't do anything in and of themselves that can cause them to disappear, however AV (antivirus) programs could potentially cause this by quarantining (I've personally never seen this happen, but you never know I guess). If this happened to you, try checking any AV software you have and make an exception for the tools.

If that doesn't work or you don't have AV, then it must be another process messing with something. You could find out which processes are causing this by using a utility like Process Monitor with these instructions.If you do figure it out, drop me a comment and I'll add your case to the FAQ for others

My plugin isn't loaded into the game!
Please first check the logs to see if the plugin is getting loaded when you start the game.

If the plugin is getting loaded, check if the plugin is compatible with your game version. If it's not, then you need to update your plugin to a compatible version. If it is compatible and still not working, then please file a bug report with the plugin dev, since this means their plugin is not working properly. If it is, and you're

, it's possible you may be

.

If you don't see the plugin getting loaded in the logs,

. This is very rare and should almost never be required, so only try this as a last resort. This only happens in cases where the user the loader is running under doesn't have required permissions to `OpenProcess` on the game (in which case, the loader will skip the process transparently, since it has no way of knowing whether it's the game process or not. This ends up with the game process not being found - and thus no plugins loaded, even though it's running)

It works, but the plugin isn't loading plugin configs!
Many native mod loader plugins are not aware of the new path to the local Plugins folder, and are hard coded to look for their configs at <game_dir>\bin\NativeMods. You can solve this by symlinking <game_dir>\bin\NativeModsto%LocalAppData%\Larian Studios\Baldur's Gate 3\Plugins

My plugin doesn't work / is broken!
If this happened, either there is a problem with the plugin, it has a bug, it was not set up correctly, or you need to update the plugin (check the authors page for an update). If it's a problem with the plugin, then you should report your bug/issue to the plugin's author/page.

I got a strange warning popup, what do I do?
Unless you're getting the warning consistently, a warning is only a warning. The winapi can - at rare times - fail and get the program into a state it cannot handle. The warning is there to just tell you that injection failed due to a rare exceptional circumstance. If this rare warning happens to you, just click Ok on the message box, restart your game, and you'll likely never see the warning ever again.

Unless you see the warnings consistently, you can completely ignore rare one-off warnings. Anything truly worthy of being an error will show an error pop up instead.

I got a warning about "game process is dirty; aborting injection" ?
"dirty" refers to the fact that the process has already been patched. It means you're trying to inject plugins into an already patched game instance. The warning is harmless.

Also see below answer.

What happens if I try to use this on an already patched game instance?
This mod loader detects if the game has already been patched and aborts patching the already patched game instance. This is done to protect your game from any potential damage. You can re-patch the game instance by restarting the game and letting the tool re-patch a fresh game instance.

I got kicked from multiplayer, why?
The cause could be (incompatible?) content mods, dll plugins, or any editing to game files you may have done. Try disabling all your mods and re-enabling them one by one to see which is the offender.

How can I debug / provide debug reports to you?
- First, open a terminal and cd to the directory your tools are in
- You can run`./bg3_*.exe --help` to see cli options (replace `*` with the actual tool name of course)
- In your console, set env var `YABG3ML_LOG="trace"`, then run `./bg3_*.exe --cli` to spawn a console the program outputs to. You will see a bunch of trace output you can use to help me debug any issues on your end

Can you support loading plugins from `<gamefolder>/bin/NativeMods` instead?
This won't be added as a feature, because one of the core goals of this mod loader is to never ever, under any circumstances, touch or mess with the game's core installation. Supporting and allowing that - even if it's only a folder - would go against this goal. However, you can move your plugins over to the plugin folder. Note, there is still a way to do this, read below!

You can still do this if you want to! Just symlink <gamedir>/bin/NativeMods to your local Plugins folder! If you'd prefer the NativeMods folder to be your "source of truth" instead, you can do the reverse and symlink the local Plugins folder path to <gamedir>/bin/NativeMods.

What are all the things this mod loader does?
This mod loader:

• checks for/creates a plugins folder and files, %LocalAppData%\Larian Studios\Baldur's Gate 3\Plugins, config.tomlfile, a log folder under the plugins folder, and log file(s) inside of the log folder
• (watcher) continually sits in the background, watching for the game process. (injector) will do the same thing, but only once (times out within 10 seconds).
• once found, it injects any enabled plugins in %LocalAppData%\Larian Studios\Baldur's Gate 3\Plugins
• injector: closes since it's done. watcher: stays open until you close it.
  

This is the entirety of the programs operation. If you read to this point, you seem curious! Why not read the source code too?

What are the deeper technical details on what this does?
In a nutshell, this mod loader uses a technique called DLL injection to inject DLLs into the game process at runtime. As such, any changes that happen to the game are done in memory onlyand no changes persist anywhere else. That makes this a very clean and efficient approach to avoid touching the actual game install.

This tool broke my game!
See the above answer on

. The answer details everything the mod loader touches, which, as you can see, is not much. This mod loader does not do anything more than what is explicitly listed there.

Because of that, any issues you have that are not specifically related to this mod loader's functionality, such as issues with your game, launcher, installation, etc, are caused by plugins, content mods (pak mods), mods which overwrite game files (whether dll or content files), or separate issues related to your OS, hardware, game and/or specific game platform launchers (steam/larian/gog); it would be best to look at one of these for the cause of whatever issue(s) you're experiencing.

Of course, if you dofind an actual issue with this mod loader, please report it!

Does it work on Linux/WINE/Proton/CrossOver?
Probably not? I don't have Linux to try it on. It may work? I honestly don't know. I don't think the code is that complex, so maybe it does. If you find out the answer to this, tell me and I can update this answer. That said, this has only been tested on a real Windows machine, so compatibility is not supported, and if it does work, is merely coincidental

How about Mac? Does it work on Mac?
This tool is incompatible with the Mac version of the game. Even if it was compatible, native plugin mods are typically dll based anyways, so the plugins only work on Windows.

I have a feature request, can I ask?
Feature requests are welcome! I can't guarantee I will implement it, but I promise to consider it, and if there's enough demand, I will try to implement it if possible

Disclaimer
This software is a hobby project. Please know that while I have made a best effort to make sure everything works perfectly and nothing goes wrong, it is still technically possible - even if highly unlikely - that something goes wrong. Though if something went wrong, it would almost certainly be due to a plugin (which I have no control over) rather than the tools. Nevertheless, by using this software, you agree to the following license terms, and you also acknowledge that you've read and followed all the instructions and warnings on the page for proper usage of the product.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.