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 any NativeModLoader plugins
  
  • This means you can develop your plugin using my Rust Native Plugin Template or NativeModLoader'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 might work on WINE if you run the Windows game under it, but this is currently untested; whether it works or not is unknown.

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

How to use

• Download the latest release
• Place the watcher.exe and injector.exe files wherever you want, maybe create shortcuts to them even.
  

If this is your first time, 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 game as you normally would*
• Run the injector tool once**
• Tool will close once done (or timeout after 10 seconds if it can't find the process)
  

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

Don't use a mod manager for installation. This mod loader was not made to be used in a mod manager. The files are self contained and can be placed and used from anywhere.

* If the tool is started too late, it's possible some plugins which expected to be started on game process startup fail to do their work properly. If that happens to you, try first running the injector within 10 seconds right before you start the game, this way it will inject exactly when the game starts, eliminating the issue.
** If the tool doesn't detect the game, even though you have the right install_root, 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. C:\Program Files (x86)\Steam\steamapps\common\Baldurs Gate 3 (note: no trailing slash! this is important, please leave the trailing slash out)
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\NativeMods to %LocalAppData%\Larian Studios\Baldur's Gate 3\Plugins so 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 use my Rust Native Plugin Template or NativeModLoader's BG3 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 server and 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 SmartScreen popup on windows when you run it. You can remove it by following these 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.

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, then try searching for other software on your computer that could be causing that. 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 running the injector, it's possible you may be running it too late. Try running it right before you start the game.

If you don't see the plugin getting loaded in the logs, you may need to run the loader as admin. 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\NativeMods to %LocalAppData%\Larian Studios\Baldur's Gate 3\Plugins

My plugin doesn't work / is broken!
If this happened, either there is an issue with your plugin, 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, 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.

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 with plugins and aborts patching the game instance if so. You can re-patch the game instance by restarting the game and letting the tool re-patch the fresh game instance.

Currently this is only a warning which you can see in the logs if this happened. I'm debating whether this should raise an information popup or not. If you have an opinion on this, let me know and I could upgrade this to a window popup instead of a silent log message.

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.toml file, 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 only and 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 "What are all the things this mod loader does?". 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 the 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 do find 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.