Testing Your Changes

The goal of this project is to have content that can be used by multiple mods. By its nature, nothing is implemented in a usable way. You'll need to make a separate testing mod that implements your changes. This involves adding spells to a spell list, passives to a progression, subclasses to a progression, etc. This is a vital step; it ensures consistent quality and functionality between all mods in the Community Library.

Even if you aren't using the Community Library, testing your mod before publishing is still extremely important. You need to make sure everything works as intended before releasing it. Otherwise, you could disappoint players with a non-functional mod or even cause serious issues with their save files or games.

Testing with Community Library

To make a build of the mod, open BG3 Modder's Multitool and drag your CommunityLibrary folder onto the "Drop workspace folder here" section. You don't need to tick the box that creates a .pak file of your mod in the Mods folder.

This will generate a .zip file in your src/BG3-Community-Library folder. If you've already installed the BG3-Community-Library mod, you're safe to just unzip the .pak file into BG3 Mod Manager, which will automatically install your mod. If not, you'll want to follow the installation instructions on the readme.

Testing without Community Library

If you're making a standalone mod without using CL resources, you can simplify the building process using Multitool. When creating your mod, tick the box that says "Pack .paks to Mods folder instead of zipping." When you drop your mod's folder onto the "Drop workspace folder here" section, the Multitool will create a .pak file of your mod in the Mods folder directly. Using BG3 Mod Manager, you can sort your mod into the load order as you would with any other mod, save it, and export it to the load order. Once you load your game, your mod will be present alongside any other mods you have installed.

Best Practices for Testing Your Mod

Start New Games

The best way to test your mod is on a new save file. You might accidentally ruin an existing save file if you load it with a new mod installed and later uninstall it. If that mod is missing when you reload that save file, you could corrupt the save or even crash your game by attempting to load content that no longer exists.

Most mods should be feasibly testable using just the content available through the Nautiloid prologue. However, if your mod requires content that must be tested at higher levels or later parts of the game, you can use these two mods to test them:

• Debug Book. This is Larian's official debug testing tool made available through a mod. It can set up Act 2 and Act 3, modify character stats, adjust companions, set and unset script flags, teleport to specific regions, and perform many more functions.
• Ring of Teleportation. This ring is a debug tool that teleports you to various locations.

Understand Different Errors

While testing, you'll encounter many different errors with your mod. Understanding what each error typically means will help you diagnose any issues with your mod.

• Multitool gives me an error when attempting to build my mod. There is an issue with your code. Multitool should provide specific file names and lines to point to exactly what command is causing an error. If it doesn't, double check your code against base game code to ensure you're using it properly.
• The changes made by my mod don't appear in-game. Run through this checklist:
  • Did you set a version number when building your mod or edit the meta.lsx file (located in ModName/Mods/Modname in your mod's folder in your workspace) to include a version number?
  • Do your folder names and folder structures match the base game folder names/structures? Use the Multitool's index to verify.
  • Do any file names that need to match existing file names match?
  • Did you follow the tutorials exactly as written?
  • Are there any other mods that change the same content as your mod? Did you test with those mods removed?
  • Did you include your changes in Progressions.lsx, ClassDescriptions.lsx, or any other file that is typically used to grant the player new spells/passives/etc.?
  • Is your code functional? Does it use provided base game commands/parameters correctly? Are the data fields for spells/passives/statuses/etc. filled out correctly?
  • Is the mod installed correctly through BG3 Mod Manager or the Community Library?
• My spells/passive/statuses/etc. show up in game but say "Not Found. You did not define localization strings and/or convert your localization .xml file to .loca using LSLib.
• My spell/passive doesn't apply a status. Double check that you're using the correct status commands/parameters, and ensure you've put the command in the correct data field for your spell/passive.
• My spell/passive/status/etc. doesn't function as intended. Keep tweaking the code until you get your desired result. Experiment with different commands and placements until it achieves exactly what you want.
• I made changes after testing, but I don't see them. Did you rebuild your mod using Multitool and correctly install it?
• Other spells/passives/statuses that I didn't mean to change were changed. You may have overwritten existing code rather than adding new code. Unless your mod explicitly aims to make changes to existing spells/passives/statuses, avoid reusing any content from them. Especially important is to avoid using the same name as an existing spell/passive/status; this is a surefire way to overwrite content by accident.

(TODO: Finish)