laughingleader / bg3moddingtools

A collection is miscellaneous snippets and scripts to make life easier when modding Baldur's Gate 3.

Baldur's Gate 3 Modding Tools

Installation

Either clone this repository, or download it as a zip with the green Code button (click Code -> Download as Zip).

Refer to the python script installation section for more information.

Snippets

Inside the .vscode folder is a file named BaldursGate3.code-snippets.
This is a snippet file for Visual Studio Code, allowing text insertion using keywords (or a shortcut if configured).

Installation

You can use BaldursGate3.code-snippets either in a .vscode folder within your project's workspace (you can create this folder), or you can place it in this folder to make it a global snippet for all workspaces:

%APPDATA%\Code\User\snippets

If you're using Visual Studio Code Insiders:

%APPDATA%\Code - Insiders\User\snippets

Current Snippets

Keyword	Description
bg3uuid	Generates a random version 4 UUID, used all over the place.
bg3handle	Generates a random localization UUID, used in files such as english.xml, StringKeyFile.lsb, root templates, character creation presets, etc.
bg3version1	The Int64 value for 1.0.0.0 - A good starting point for mods. Use in your mod's meta.lsx.
bg3dependency	Inserts a ModuleShortDesc node. Goes under the Dependencies node in a meta.lsx, or can be used for entries under the Mods node in modsettings.lsx.
bg3modmeta	Generates the contents of a full Mods\ModName_UUID\meta.lsx.

Python Scripts

A collection of python scripts are within the scripts folder, allowing various utilities through the commandline. Some may require LSLib for full functionality (download the latest release, and keep track of where divine.exe is).

Installation

Requirements

• Python (3.10 or higher, though higher versions may have breaking changes)
• LSLib
• ImageMagick (Required if you want to use convert_images.py)

After python is installed (or if it was already installed), make sure to install required packages with this command in the command line, or double click InstallScriptRequirements.bat:

pip install -r scripts/requirements.txt

This will download the necessary packages used by the scripts. Note that the path to requirements.txt is relative to wherever the command prompt's working directory is (so if you open BG3ModdingTools in VSCode, it'll be in the scripts folder like above).

Environment Variables

The scripts will check for specific environment variables, which will allow you to omit various arguments, for easier use.

Name	Description
BG3_PATH	The path to the Baldur's Gate 3 root folder, i.e. C:\Program Files (x86)\Steam\steamapps\common\Baldurs Gate 3
LSLIB_PATH	The path to wherever you extracted an LSLib release, i.e. C:\Modding\BG3\Tools\ConverterApp
BG3_EXTRACTED	The path to all of Baldur's Gate 3 extracted data. This is used for certain scripts like extract_game for automatic output.

How to set Environment Variables

1. Hit the Windows Key.
2. Type "environment", then click "Edit the system environment variables" in the search window.
3. Click the "Environment Variables" button in the window that popped up.
4. Under "User Variables for Username", click "New" to add a variable, then enter the name and path as specified in the table above.

You may need to restart the command prompt, or enter the refreshEnv command (if you have chocolatey) to refresh all environment variables, so python will see them.

bg3moddingtools's Issues

`extract_game.py` silently fails

I'm trying as simple of a command as python .\scripts\extract_game.py -g All, I see a successful scrollbar, but I do not have any actual extraction. The reason why is my files are being stored in a folder with an apostrophe.

Extracting game data to C:\Users\woovi\Baldur's Gate 3 Modding\Extracted
Extracting Assets.pak...
[divine]
'C:\Users\woovi\Baldur's' is not recognized as an internal or external command,
operable program or batch file.
[divine] exited with code [1]

As well, I was never able to see output via CLI beyond that loading bar. If I pass no parameters, I get no output. I temporarily modified log() in common.py, setting do_print to True by default instead. It was difficult to understand exactly what was going on with no feedback and no output.

If we add a debug print of the final cmd variable passed to asyncio.create_subprocess_shell(), the issue is clear:

on 27: Extracting English.pak...
on 27: C:\Users\woovi\Baldur's Gate 3 Modding\ExportTool-v1.18.5\divine.exe -g bg3 -s "C:\Program Files (x86)\Steam\steamapps\common\Baldurs Gate 3\Data\Localization\English.pak" -a extract-package -d "C:\Users\woovi\Baldur's Gate 3 Modding\Extracted" -i pa

https://github.com/LaughingLeader/BG3ModdingTools/blob/master/scripts/extract_game.py#L91-L92

I tried a few things, like doing .replace("'", "''") along side single quotes around the entire path and & before the process name, couldn't figure out a good solution. Ultimately I gave up and renamed the folder. I would like maybe some error output if divine.exe had a non-zero exit code? I am not sure about fixing the quote issue, I tried a few things, hopefully someone can find a good solution.

Most scripts not working since LSLib v1.19.4

Assembly.LoadFrom seems to work
as well as clr.AddReference
but from LSLib.LS import ... & from LSLib.LS.Enums import ...
shows **ModuleNotFoundError**

Traceback (most recent call last): File "E:\BG3 Mods\Modding Tools\For Upload\scripts\convert_lsf.py", line 97, in <module> run(lslib_dll, input_file, output_file, batch, in_type, out_type) File "E:\BG3 Mods\Modding Tools\For Upload\scripts\convert_lsf.py", line 29, in run from LSLib.LS import ResourceUtils, ResourceConversionParameters, ResourceLoadParameters # type: ignore ^^^^^^^^^^^^^^ModuleNotFoundError: No module named 'LSLib'

`extract_osiris.py` fails due to LSLib

With the latest stable LSLib (1.18.7) and a save file, extract_databases.py gives basically the same error shown in Norbyte/lslib#209.
(When given story.div.osi instead of a save file, it doesn't error but also doesn't output anything.)

But with the pre-release version of LSLib that apparently fixes that (1.19.3), extract_databases.py gives what looks like an import error:

Traceback (most recent call last):
  File "D:\GitHub\BG3ModdingTools\scripts\extract_databases.py", line 94, in <module>
    from LSLib.LS import PackageReader, Package, AbstractFileInfo, LSFReader # type: ignore
ModuleNotFoundError: No module named 'LSLib'

Please advise?

Also, what exact version of python are you using? Because 3.10.11 is giving me huge problems when trying to install all the requirements.