Setting up a Development Environment

You may find it useful, if contributing, to have a development environment ready for making contributions. You can, of course, rough it with Notepad, but a few specific tools will make your life much, much easier.

Recommended/Required Tools

BG3 Modder's Multitool

This makes the process of mod-making significantly easier. It automatically builds your mods (known as paking), indexes your game files (making searching game files easier ), and will soon have a powerful Mod Editing GUI component. It can also generate GUIDs for you.

Export Tool v. 1.18.5 or higher

This is an important tool to have when modding Baldur's Gate 3. It performs various functions related to modding. One of its most important features is converting localization .xml files to .loca.

BG3 Mod Manager

This simplifies the mod installation process. You can drag the .zip file of a mod into this program, and it will install it automatically for you. All you have to do is drag it from the inactive load order to the active load order, click Save, and click Export. You can also adjust the load order of your mods, which prevents conflicts and ensures functionality between mods that depend on other mods to function.

Git

Because we're using Github, Git is the preferred version control system for this project. If you don't have Git, we highly recommend it as a way to handle versioning and manage your code. It's a lifesaver.

Visual Studio Code (or Notepad++)

Visual Studio Code(VSCode) is the preferred file editor for this project. Notepad++ works, as does Notepad (though you'd be doing yourself a disservice), but VSCode shines due to many different features:

• The UUID Generator add-on adds a keyboard shortcut (Alt+Shift+U) to generate a GUID. When working with .lsx files, this is a massive timesaver. You can make GUIDs while coding rather than shifting to another page or application to generate and copy one.
• The BG3 Text Support add-on automatically applies colorization for Data items (often stored in .txt files). This makes it easier to spot faulty data entries and just generally makes coding easier on the eyes. It includes syntax highlighting, auto-formatting, and customization capabilities.
• VSCode has a Project Folder Sidebar. You can designate which folder is your Project folder, and it will display a tree view of all folders and files within the Project folder. This makes it easier to get to or create the file you need. By selecting your main modding folder, you can view any unpaked data files from the game in the Multitool's folder.
• VSCode autofills commands across files. For example, if you've added a status entry in CL_Status_BOOST.txt, you can start typing it and select the full name from a list. It can also search every file in a project at once. This is especially useful if you need to find and replace every instance of a UUID.
• VSCode can display multiple files at once in the same window. Notepad++ can display up to 2 files side-by-side. I'm not really sure if Atom has a limit, but it can display at least 8 files at once. I find a three file layout works best for me.
• VSCode has Github integration built in, letting you to fetch, change branches, and more, all from within the editor. This can be especially useful if you're not a fan of using git via the command line.

Getting Started

Once you have those set up, you'll want a good working folder for your development. Personally, I use a folder, BG, in my Documents folder. Going forward, this guide will be written with my set-up in mind, feel free to change things as needed.

In BG, I have a few folders: Export Tool, LL BG3 Mod Manager, and src.

• Export Tool
  • As you may have guessed, this contains Export Tool. It also contains the latest release of BG3 Modder's Multitool
• LL BG3 Mod Manager
  • This contains BG3 Mod Manager, which I've found to be a reliable Mod Manager. Manual Installation is a thing, as is Vortex, but I've found this one easy to work with.
• Src
  • This contains subfolders for any mods I'm working on. You'll want to take the following steps at this point.
    1. Open Gitbash(If using Windows) or Terminal(If using Mac/Linux)
    2. Navigate to your src folder
    3. Input: git clone https://github.com/BG3-Community-Library-Team/BG3-Community-Library.git
  • This will give you the latest version of the Repo! Let's take a look at BG3-Community-Library:

You may be wondering why the Release folder isn't present. This folder is set to not be tracked by git, using the .gitignore file. NellsRelo/khuckins, or the Release Manager, if such a role is created, will handle the creation of Releases. Just for reference, though, this is what it looks like:

Forking the Repo

Now that we've got the repo itself cloned, lets make our fork.

1. Hit the "Fork" button on this repo's page, and select your account when prompted.
2. In Gitbash/Terminal, navigate to the src/BG3-Community-Library folder
3. Input: git remote add working PersonalRepoLink.git

Git Practices

Since not everyone knows git, a quick mini-primer may be useful here. One of Git's most well-known features in Branching. When working on a new feature, it's best to do the following: git checkout -b FeatureBranchName. This way you can switch back and forth between the original content and your changes as needed. Generally, before switching branches, you'll want to be sure to commit your changes:

git add ChangedFiles, separated by spaces
git commit -s

Note than when using git add, you can enter a Directory name, and all files and folders within that directory will be added to your commit. For this project, don't use git add *, as you may inadvertently add files that you don't want to have tracked.

Also note that we're not using -m with git commit. -m is handy in some cases, but it prevents thorough commit descriptions. git commit will take you into a virtual text editing environment. The first line will be the title of the commit - you'll want it to be just descriptive enough that it's not too long, but explains the purpose of the commit. Make two line breaks after the title, and then make a bullet-point list of changes made. For example:

Bound Weapons + gitignore additions
- Ignore .zip files
- Add Bound Weapon Spells/Scripts

The -s also appends a virtual signature, which isn't really necessary, but it looks classy ;)

Testing your changes

So, here's the tricky part. 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, so what gives?

Yeah, you'll need to make a separate testing mod which implements your changes. Typically this will be very simple, usually involving adding spells to a Spell list, or Passives to a progression. This is a vital step, though, as it helps ensure consistent quality.

To make a build of the mod, you'll want to utilize BG3 Modder's Multitool, dragging your CommunityLibrary folder onto the "Drop workspace folder here" part of the multitool. That will generate a .zip file in your src/BG3-Community-Library folder. If you've already installed BG3-Community-Library, you're safe to just unzip the .pak file into your Documents/Larian Studios/Baldur's Gate 3/Mods folder. If not, you'll want to follow the installation instructions on the readme. Note that it may be easier just to reimport the .pak file via BG3 Mod Manager

Making a Pull Request

Now that you've tested your changes, in Gitbash/Terminal, you'll want to perform git push working BranchName. Just for the sake of thoroughness, let's deconstruct that: git push pushes your commit up to Github. Without any arguments afterward, it will assume origin, which in our case is the community repo. Not exactly ideal, and settings should disallow that anyway. That's where working comes in. working, as you'll recall, points to your personal repository. Finally, BranchName, changed to match whatever you've named your branch, just points git in the right direction if it can't tell where the right upstream branch is.

With that out of the way, now you'll want to make a Pull Request. You can put the Command Line away now, as it's not needed at this point. On your personal Repo on Github, after making a push, in your browser you should see a prompt to make a Pull Request. Otherwise, you can go to the Community Repo's "Pull Requests" tab, make a new pull request, and be sure to select "Compare across forks." You should see your repo in the repo list on the right - from there, select your branch. On the left branch list, "base", select the dev branch that your feature is using as a milestone. Typically this is the dev branch with a version one point ahead of the current release. Then hit "Create Pull Request."

The Review Process

In this step of the process, a contributor with merge permissions will review your changes, and perform their own test. Afterward, they'll provide feedback if needed, and either deny(with feedback as to why it's not ready/won't be accepted) or accept the pull request, merging into the next milestone dev branch.