A New Player’s Guide to Installing and Playing Mods
This is a guide intended for players who are interested in modding their game, but may be overwhelmed by the options or the installers, and to hopefully troubleshoot common issues.
A brief overview of modding the games
Modding games using the Infinity Engine—the engine that runs the original and Enhanced Editions (EEs) of the Baldur's Gate, Planescape: Torment, and Icewind Dale games—revolves around a tool named WeiDU (the Weimer Dialogue Utility). It's a very powerful tool for modders and allows for a high level of interoperability between mods. For players, the important things to know about WeiDU are:
For Windows and macOS players, WeiDU is included with mods. It’s not something you need to download yourself.
Linux users will need to do a one-time install of WeiDU (and a few other adjustments): suy has a great writeup here.
WeiDU installs mods through a command-line interface, e.g. on Windows it does everything through the Command Prompt, a DOS-like interface
WeiDU allows mods to affect previously installed mods, making install order important, as we’ll discuss in a later section. WeiDU also has built-in mechanisms to preserve the order you select.
WeiDU allows mods to be broken down into individual components so that players can pick and choose what they want from a particular mod
WeiDU can uninstall or reinstall parts of mods
Modding a mobile or console version of IE games requires more hoops to jump through, and will not be covered here.
Important warnings before you install
Changes from mods will end up in your save games. The practical upshot of this is that a save from a modded game will only reliably work with the particular modded game that it's from—changing or uninstalling mods mid-game may cause your save to not work.
The Enhanced Editions are still being actively developed by Beamdog. When a new official patch is released, the update process removes any outside files, with the effective result being that your mods get wiped out by a new patch. Coupled with the above point, it may mean you cannot use your old saves from modded games.
Multiplayer games must all use the same mods in the same order. The host and clients in a multiplayer games must have matching resources, otherwise the game may be unstable (if it allows you to connect at all).
The takeaway is that you're better served making a copy of your game to use with mods, and that you should not change your mods in the middle of a playthrough (or, alternatively, abandon any existing saved games if you do). The downside of playing off a copy of your game is that your Steam/GOG Galaxy launcher will try to launch the original unmodded game and that you may not get achievements.
For the EEs, making a new game install is easy: just copy the game folder and mod the copy. It's almost as easy for the originals. On Windows, make your copy outside of the "Program Files" or "Program Files (x86)", as Windows can sometimes interfere with the installers trying to make changes inside these folders.
What about mod managers?
While there is a proliferation of mods, there have been few notable attempts at a mod manager. There are four of note, and all but one are for Windows:
The Big World Project/Big World Setup (BWP/BWS): This was a combination of an install tool and database of installation order information for the original games. Unfortunately, the sheer magnitude of the project—namely trying to keep track of the optimal order of hundreds of mods as well as their conflicts—was simply unmanageable. While the database of mods and install orders still gets sporadic updates, the tool itself has not been meaningfully updated in years.
Project Infinity (PI): Project Infinity is a new tool from one of the BWS authors, and worth a look. Its goal is to provide the same level of functionality as BWS without the unmaintainable aspects of the project, e.g. it gives optional tools for modders to provide install order information, or you can use community-derived install orders. PI is still in development.
The Mac WeiDU Launcher (MWL): Worth a look as well, the WML is a utility for macOS that will allow you to install mods on macOS without having to muck around at the command-line.
EE Mod Setup Tool: A fork of the old BWS tool for the new EE games. Unfortunately, the project uses unofficial, outdated, and unsupported versions of mods added against the authors' wishes.
Gather your mods before venturing forth
Sorting out which mod should get installed in what order can be difficult even for veteran players, so keep it simple for your first time. Maybe you have your eye on a new NPC, or see some kits that look fun, or want some quality-of-life changes.
Most mods are hosted by one of the big modding communities: The Gibberlings Three (G3), Pocket Plane Group (PPG), Spellhold Studios (SHS), or Weasel Mods (WM). You can also find some on the Beamdog forums or other communities. For most mods, you can check out the readme as a preview before deciding whether or not to download and play it. While some mods are packaged with a “universal installer”, most will have platform-specific packages (Windows, macOS, or Linux) so make sure you download the correct version. (Note that some mods still refer to macOS as OS X.) Always uses the latest official release of a mod; e.g. don't download the latest 'master' from Github or something you find on a random Dropbox. If you're unsure if whether you have the latest and greatest, ask on the forums!
Unfortunately, there’s not a lot of consistency on how mods are packaged. On Windows, mods are generally rar/zip files or self-extracting archives or even with a full installer. The former need to be extracted, and the latter will extract themselves and (usually) try to start their installation process. For macOS and Linux, the mods are simply packaged as zips or tarballs.
For now, just download the mods into a separate folder.
A brief aside about conversion projects
There are a handful of larger conversion projects that essentially bring the contents of one game into another, typically because the latter’s engine provides some advantage or convenience. While these conversions have become a lot easier and bulletproof and are generally all-around high-quality mods, they’re still not something I’d recommend for a new mod player. A brief overview of the more popular conversion mods follows:
Baldur’s Gate To Two (Tutu) is a project for the original games. It brings the content of BG into the BG2 engine, allowing you to play through the story of Baldur’s Gate with the conveniences of BG2, such as kits, dual-wielding, better resolutions, expanded spell selection, etc. Once you complete Tutu, you have to export your characters to a BG2 installation to continue.
Baldur’s Gate Trilogy (BGT), like Tutu, is a mod for the original games that imports BG content into BG2. Unlike Tutu, though, it combines BG and BG2 into a single, playable experience from the start of BG in Candlekeep through the saga’s conclusion in BG2’s Throne of Bhaal.
Enhanced Edition Trilogy (EET) is like BGT, except it’s for the Enhanced Editions of the games. EET is a little more expansive than BGT but is still in development and requires some extra care with install orders. As such, it's not something I'd recommend for a player new to modding. .
Mods known as Total Conversions (TC) aim to replace the entire content of a game with alternative content. While such mods are uncommon, I'd still recommend players to avoid these for their first time, as they come with their own set of compatibility issues to be resolved.
Sorting out the install order
Since WeiDU mods can not only change game resources, but content from other mods, it becomes important to resolve an installation order before you begin. A good general guideline is as follows:
Special: If you're modding a game with Siege of Dragonspear from Steam or GOG, you must run a mod called DLC Merger on your game before you can install any other WeiDU-based mod. Some mods may recommend a program named ModMerge instead, but DLC Merger is the preferred method these days.
Fixes. Many mods create new resources from the existing ones, so getting in the fixes early prevents errors in the original files from propagating to mod files. Examples include the BG2 Fixpack or the IWD Fixpack.
Atypical Content Mods. This category is a little hard to describe. There are some mods that don't really interact much with other mods (e.g. Ace's Alternate Soundtrack) or which are designed to only alter original game files (e.g. Improved BAMs) without worrying about modded content. Because of how WeiDU handles and preserves installation order, the earlier you can place mods like this the easier it will make any future mod updates to your installation. This is also a pretty good place for item/store mods, especially if they're stable and unlikely to be updated often.
Quests/Other Content. Once you've got a solid base, it's time to start adding actual content. Examples include Ascension or BG Quests and Encounters.
NPCs. NPCs should go after quests simply because some NPCs will detect modded quest content and provide interaction with it. You may find a mod NPC commenting on a mod quest, but only if the NPC follows the quest in the installation order. Examples include Mur'Neth and Amber.
Tweak mods/tactical mods. Most in this category are written to be universal, i.e. they'll freely change items/creatures/scripts/etc. from other mods, but they can only do so if those resources are present when they're installed. This is why just about every tweak mod suggests it goes last in the install order. Examples include Sword Coast Stratagems and Tweaks Anthology.
Within each category, another good rule of thumb is to go with older mods first.
There are, of course, all sorts of exceptions, or mods that really don't fall cleanly into a category. The readmes are there for a reason, and most modders try to help players avoid issues with install recommendations and compatibility concerns. If a mod has a forum, it’s also a great resource to learn about where it should go in the install order.
Once you have an order in mind, feel free to ask other players about it.
Can we please just install some mods, finally?
OK, so let’s recap our preparations:
We’ve made a copy of our game to mod.
We’ve downloaded the mods we’d like to play into a folder.
We’ve read the readmes for these mods, double-checking that they’re compatible with one another.
We’ve decided on an installation order for these mods.
So let’s get started with a mod installation. A few points before you begin:
Do not install mods while the game is running.
Do not install mods while a game editor is running, e.g. EEKeeper, Near Infinity, etc.
Only install one mod at a time.
Never close the installer window by using the 'X' in the upper right corner. Always properly quit the installer.
I’ll be using Tweaks Anthology as an example.
Tweaks Anthology for Windows is distributed as a self-extracting archive. You can double-click the archive and follow the instructions on screen and it will launch the installer.
Alternatively, the files can be extracted into your game directory using 7zip or WinRAR. When properly extracted, your game directory will contain setup-cdtweaks.exe and the folder cdtweaks. To install, double-click setup-cdtweaks.exe.
At a minimum, every mod will add a folder and a setup-ModName.exe file to your game folder. Some mods include their readme file and a tp2 file in the game directory, but most mods these days place these inside their own folder.
Either way you choose, once the installer is open, skip ahead to the "The installer is running" section.
The Tweaks Anthology for macOS is distributed as a compressed tarball. First, extract the files from the tarball into your game directory. When properly extracted, your game directory will contain setup-cdtweaks, setup-cdtweaks.command, and the folder cdtweaks. At a minimum, every mod will add a folder, setup-ModName, and a setup-ModName.command file to your game folder. Some mods include their readme file and a tp2 file in the game directory, but most mods these days place these inside their own folder.
Once the installer is open, skip ahead to the "The installer is running" section.
Provided you've already installed WeiDU (a one-time affair), install is simple. The Tweaks Anthology for Linux is distributed as a compressed tarball; extract the contents of the mod to the folder of the game you wish to modify. Use cd to change to your game installation directory, and run WeInstall cdtweaks in your game folder.
Once the installer is open, continue below.
The installer is now running
On Windows and macOS, the first thing the installer tries to do is update itself to the latest version. It does this by checking for other WeiDU installers; this process is automatic but it may create a few messages at the top of the installer window (blue in screenshot, below)
[Optional] Next, if a mod is available in multiple languages, it will ask you which language you want to use (red, below). If a mod does not have translations, you will go to the next step.
[Optional, One-Time] If you're modding an Enhanced Edition game, the very first time you run a mod, you will be prompted to select a language for the game itself (red, below). Note that this order of languages will likely differ from a mod's language selections. If you select the wrong language in this step, all of the new mod text will show up as "Invalid:xxx". If you accidentally select the wrong language, quit before installing anything, delete weidu.conf from your game folder, and start over.
[Optional] Some mods will include a prompt to display the readme (red, below) before continuing. Selecting yes or no will not change the rest of the installation.
[Optional] Larger mods, such as Tweaks Anthology, will break their individual components into categories--five in this case: Cosmetic, Content, Rule Changes, Convenience Tweaks/Cheats, and NPCs (red, below). This will allow you to skip entire sections of the mod if you're not interested; select yes or no as appropriate.
Finally, we're at an actual component to install (red, below). You're prompted with the name of the component (Remove Helmet Animations) and prompted to answer
[I]nstall - install the contents of this component
[N]ot install - Do not install this component
[Q]uit - Quit the installer completely with no further changes.
If you choose to Not Install, the installer will move on to the next component.
If you choose to install, the installer will start making changes and will provide feedback (red, below) in the window:
Once it's done, it moves on to the next component. Note that, in this case, the installer has skipped some components automatically (blue, above). I'm running the installer on Icewind Dale, so it automatically skips components related to Imoen, Nalia, and Viconia since they're not in Icewind Dale.
Once you select quit, or reach the end of components, WeiDU will provide a brief summary (red, below) and prompt you to press Enter to exit.
Simply repeat this process for each individual mod.
Troubleshooting installation issues
Problem: When you try to launch a mod installer, you see the message
"Please run this program in your Infinity Engine game directory.
FATAL ERROR: Failure("Not a game directory")
Press ENTER to exit."
Solution: You've launched the installer somewhere other than your game directory. Simply move the files into your game directory and try again.
Problem: When you try to launch a mod installer, you see the message
"ERROR: Unable to find DIALOG.TLK in:
Please run this program in your Infinity Engine game directory.
FATAL ERROR: Failure("Unable to find DIALOG.TLK")
Press ENTER to exit."
Solution: You've launched a mod with a very old version of WeiDU on an Enhanced Edition game. It's unlikely this mod will work on the Enhanced Editions even with a newer version of WeiDU; check the mod's home page for an updated version.
Problem: A mod installs "with warnings"
Solution: "With warnings" means that a mod installed, but it may not have modified all the resources that it expected to modify or files were unexpectedly different. Check with the mod author or visit the mod's forum to find more information. It could be harmless, e.g. the mod is being careful, or it could be something worse.
Problem: A mod encounters an error and fails to install a component.
Solution: In this case, there's something wrong in the mod itself and you'll need to contact the author. In your game folder, WeiDU creates a text file named "SETUP-MODNAME.DEBUG". Send this to the author or post it to the mod forum with as much information as you can. Some authors will also request a copy of weidu.log, a text file that contains a list of all installed mods, to help them investigate if the issue is with another mod.
You've modded your first game!
Huzzah! Now go play it!
The keen-eyed will notice you have some new files in your game folder; these files are needed and should not be deleted. Every mod generates a DEBUG file, which is a log from the mod's installation. You will also have one weidu.log file, which keeps track of which mods and components you have installed, and in what order. On EE games, you will also have a weidu.conf file which WeiDU uses to track which language of the game you're modding.
Every mod also keeps a backup folder so that it can be uninstalled. Typically these are kept inside the mod folder (e.g. the one for Tweaks Anthology is in cdtweaks/backup) but some use a folder named weidu_external. Because these are needed for future changes (or uninstalling), you should never delete a mod folder if the mod is installed.
If you should run into a bug, please report it. Authors don't like having a buggy mod any more than you like playing it, but they can only fix bugs they know about. Have your DEBUG file handy! If you're not sure which mod is causing a bug, report it to any author whose mod it might be or feel free to ask on some general discussion forums or Discord.
Again, because I cannot emphasize this enough: please report bugs to the authors!
I've changed my mind, I want different mods
You can change your mod selection at any point. However, there are a few caveats:
As mentioned above, mod content can get included in your save game and there is no guarantee that your old save games will work with your new mod selections. As such, you should plan on starting a new game if you change your mod loadout.
Because of WeiDU's onion layer approach (see below), if you're making a lot of changes it may be easier to start over with a fresh copy of the game.
You can uninstall or re-install a mod by re-opening its setup program. Instead of Install/Not Install/Quit, prompts for components that are installed are now Reinstall/Uninstall/Quit. If you uninstall or reinstall a component, WeiDU will try to preserve your mod order. Let's say you've installed some mods on BG2, in this order:
Arcane and Divine Spell Packs, from IWDification
The G3 Anniversary Mod
Wheels of Prophecy
Multiple components from Tweaks Anthology
After thinking it over, you've decided that the G3 Anniversary mod isn't for you. So you open up the G3 Anniversary setup program and select Uninstall. Wait, why is WeiDU uninstalling Tweaks Anthology? And now Wheels of Prophecy?
WeiDU acknowledges that you're removing G3 Anniversary, so it's goal is to make your installed mod order this:
Arcane and Divine Spell Packs, from IWDification
Wheels of Prophecy
Multiple components from Tweaks Anthology
It accomplishes this by treating the mods as layers of an onion: it will uninstall all of the components from Tweaks Anthology, then uninstall Wheels of Prophecy, then uninstall G3 Anniversary, then (to preserve your mod order) it will re-install Wheels of Prophecy and then re-install your previous selection of components from Tweaks Anthology. It will remember and re-apply whatever you have selected from Wheels and Tweaks; you do not need to select these again.
Similarly, if you have a modded install and decide to add more mods, they will be added to the top of the stack--which may not be an ideal place in the mod order.
Some final tips and closing comments
One more time for the kids in the back: please report bugs to the authors! Make a separate game folder to be modded. Don't install mods while the game is open and always let the installer finish.
For troubleshooting bugs encountered in game, it may be beneficial to enable the console. You can learn how to enable the console and find some useful commands here: Enhanced Editions (all games) or the original versions of BG, BG2, IWD, or IWD2.
There are lots of folks who love these games, and love them even more when they're modded. Feel free to come and talk with them on the forums or on Discord!
I'd like to thank folks who were kind enough to provide feedback on earlier drafts: @AL|EN, @Angel, @DavidW, @jastey, @Mike1072, @suy, and @theacefes.
If you have any suggestions or questions, feel free to reply and I'll do my best to answer.
9/12/21: Added information on the Mac WeiDU Launcher