【 BG3 Toolkit 】Tutorials & Resources Megathread

[loregamer]

Figured we can use a thread for this. Write up any findings or questions you have and I'll link it in an index like this:

Index

1. Changing NPC Visuals
   • How to use the Character Editor
   • Editing Default Tav Presets
   • Generating Portraits
2. Editing Dialogue
   • Adding new Voice Lines and lip-syncing them
   • Overriding existing Voice Lines
   • Altering Dialogue Nodes & Flow
   • Editing Localization Lines
     
3. Creating a New Level
   ㅤ
4. Adding a Custom Origin in BG3
   ㅤ
5. Converting Existing Mods to Toolkit
   • Separate LSX Into Separate LSF Files For Toolkit
   • VOICE MOD COMPATIBILITY SCRIPT
     
6. Setting Up a MO2 Instance - Keep Your Game Files Clean (TBD)

---

Unlocking The Toolkit
To unlock the full functionality of the toolkit, visit the Modding Toolkit Unlocked thread and follow the installation steps.

This will unlock all features and write permissions for the BG3 Toolkit including level editing, save editing, and more.

---

For converting your existing mods or quickly managing your toolkit project, check out this tool:
BG3 Toolkit Helper

[jebacdrkac]

does the toolkit work with pirated BG3?

[loregamer]

Editing Default Tav Presets
Tutorial from Padme4000, but I used AI to make him sound more like himself and not the gross troon voice.

[rusty_shackleford]

Editing Default Tav Presets
Tutorial from Padme4000, but I used AI to make him sound more like himself and not the gross troon voice.

ffmpeg -i in.mp4 -c copy -movflags faststart out.mp4
https://superuser.com/questions/856025/ ... -parameter

I need to change vault to do this automatically

[loregamer]

ffmpeg -i in.mp4 -c copy -movflags faststart out.mp4
https://superuser.com/questions/856025/ ... -parameter

I need to change vault to do this automatically

Did it, I think

[Vergil]

Editing Default Tav Presets
Tutorial from Padme4000, but I used AI to make him sound more like himself and not the gross troon voice.

Okay now one for editing origins pls

[DagothGeas5]

It might be covered in the dialogue part in the future, but I am very curious about the facial animations, gestures, and all the rest that happen during dialogue for this game. They butchered Astarion's movements and camera angles in the "full" version, but how would it be possible to re-do or even make new animations? Would it require mo-cap or some 3D animating skills, or are there a set of animations that can be chosen and applied like it was in Skyrim?

[Statesman]

does the toolkit work with pirated BG3?

At least the GoG version does.

[Statesman]

Dialogue and Timeline Cinematics Intro

► Outdated

Adding Basic Dialog to your Level

[Statesman]

LSLib - PAK Exporter Tool

This package provides utilities for manipulating Divinity Original Sin 1, Enhanced Edition, Original Sin 2 and Baldur's Gate 3 files:

• Extracting/creating PAK packages
• Extracting/creating LSV savegame packages
• Converting LSB, LSF, LSX, LSJ resource files
• Importing and exporting meshes and animations (conversion from/to GR2 format)
• Editing story (OSI) databases

Releases

[Statesman]

Creating a New Level

[Statesman]

Okay now one for editing origins pls

Close enough?

Adding a Custom Origin in BG3
Rough guide made by Passke on how to add custom characters. Keep in mind unique characters might have some specific things needed to work including story scripts (Since I added the default setup to origin characters unique before it would work).

[Vergil]

Okay now one for editing origins pls

Close enough?

Adding a Custom Origin in BG3
Rough guide made by Passke on how to add custom characters. Keep in mind unique characters might have some specific things needed to work including story scripts (Since I added the default setup to origin characters unique before it would work).

Nah I mean like editing the appearance, dialog, and voice clips for companions.

[Statesman]

Nah I mean like editing the appearance, dialog, and voice clips for companions.

Ah, well you can modify appearance without the Toolkit, with the Toolkit and even with mods Appearance Edit Enhanced (if you don't plan on sharing them). Haven't seen a guide using the Toolkit yet, but it probably is close enough to the the other Divinity Engine games. Or just ask orinEsque for help with the older methods.

Besides that, I posted a video on how to edit dialog above (a bit clunky, but it does work). Now voice clips are a headache, you'll need a trained AI Voice Model (beyond my expertise atm). You'll also lack lip-sync on new lines, but there are some people working on fixing that particular issue (apparently Starfield uses the same lip-sync tech, so someone will figure it out eventually). So TLDR, we are halfway there.

[Vergil]

Or just ask orinEsque for help with the older methods.

Are you threatening me?

[Statesman]

Or just ask orinEsque for help with the older methods.

Are you threatening me?

No, lol. We have several other BG3 modders you could bother if, for some reason unknown to me, you'd feel more comfortable asking them. She was just the first user that came to mind when thinking about NPC appearances

[Statesman]

Adding new Voice Lines and lip-syncing them

@Vergil Getting closer...

[loregamer]

Altering Dialogue Nodes & Flow

---

1. Create a new mod project
2. Open any level (doesn't matter)
3. Open the Resource Manager
   
4. Click "All" on the left sidebar, and search for the dialogue you are trying to alter.
   • Not exactly sure how to find the exact correct one, but for instance, I wanted to alter the conversation with Astarion at the tiefling party. The one to edit is CAMP_GoblinHuntTieflingCelebration_CRD_Astarion
   • I assume you can just filter by DialogResource and then deduct from there
5. Right click on it, and Override in active mod
   
6. Click "Yes" on maintaining the same package structure
7. Find the new Dialogue Timeline on the left panel and you should see a new duplicate of the DialogResource
   
8. Double click on it
9. Make your changes
10. Save, ignore any warnings
11. When ready, go to Project > Project Settings > Publish Local

[Xenich]

Anything on core mechanic changes for adapting to different systems? Possible or hardcoded?

[Kowe]

Anything on core mechanic changes for adapting to different systems? Possible or hardcoded?

These may interest you:

Script Editor - Can be for itemScripts and GameScripts.


StoryEditor - Also includes scripts.


Just glanced over them.

[Xenich]

Anything on core mechanic changes for adapting to different systems? Possible or hardcoded?

These may interest you:

Script Editor - Can be for itemScripts and GameScripts.


StoryEditor - Also includes scripts.


Just glanced over them.

Thanks, I guess I will have to load things up and start toying with them. I don't have BG3 installed atm which is why I was wanting to avoid doing so if it were a quick answer. I spent a lot of time browsing through the DOS editor a while back to run into a dead end for what I had in mind.

Basically I was looking to see where systems like AC and "to hit" are handled in combat as those would be major revisions at their core to adjust for 1st/2nd edition. If that is hardcoded in a way where it could not be easily manipulated, you would have to rely on the scripting engine to adjust it mid process (which could cause its own issues).

Depending on how flexible the engine is though (hoping) the goal would be to see if it could be further adapted outside of D20, and allow for some other system implementations like Shadowrun's D6 system for instance.

Anyway, like I said, I am probably going to have to get my hands dirty eventually I guess (don't have the time at the moment). That or hold off and wait for people to find out more anyway, as it seems a lot of people are delving into it pretty deep.

[loregamer]

For converting your existing mods or quickly managing your toolkit project, check out this tool:
BG3 Toolkit Helper




You will need to separate all your LSX's that contain multiple resource nodes into separate ones named off of UUID.

[orinEsque]

Editing Dialogue
Its now possible to only change specific lines

1. Put your line changes in an english.xml file under the following structure
   YourMod/Mods/YourMod/Localization/English/english.xml
   
   Note: For a french translator this would be: YourMod/Mods/YourMod/Localization/French/french.xml
2. Add the original line in this structure:
   
3. Alter the lines and increase the version number of each line by 1
   
4. Pack the mod using BG3 modding tool or official mod kit.

Important: lingo files no longer take notes or free text out side tags. If you add them, your game will crash.

[orinEsque]

Separate LSX Into Separate LSF Files For Toolkit
...

You need to add exceptions for GameObjects, which have node id=GameObjects, and instead of ID it's called MapKey

You can also run converter tool from inside python [if you bake it in for people].

for example this is how I convert xml to loca programmatically in R:

Code: Select all

# Convert to Loca
setwd("F:\\My Documents\\BG3_modding_dev\\ExportTool-v1.18.7\\Tools")
tool="divine.exe"
type="convert-loca"
game="bg3"
source='"F:/My Documents/BG3_modding_dev/my_mod_no_alphabets/NoAlphabetsLingo/NoAlphabetsLingo/Mods/NoAlphabetsLingo/Localization/English/english.loca.xml"'
dest='"F:/My Documents/BG3_modding_dev/my_mod_no_alphabets/NoAlphabetsLingo/NoAlphabetsLingo/Mods/NoAlphabetsLingo/Localization/English/english.loca"'

system(paste0(tool
              , " -a " , type
              , " -g " , game
              , " -s " , source
              , " -d " , dest
))

CLI interface for BG3 Multimodder tool
https://github.com/ShinyHobo/BG3-Modder ... -Interface

CLI interface for Convertor tool
Command line exists but Norbyte never made documentation for it. You can figure it out from this file:
https://github.com/Norbyte/lslib/blob/m ... guments.cs

This guy made some documentation of the old divine.exe. Some conversions like convert-loca is missing in his manual.
https://github.com/fireundubh/divine

[orinEsque]

Portraits
https://docs.google.com/document/d/1bEC ... mjcoc9krqc

► Old Instructions

Generating Portraits
Note: You need to create a portrait generator for every mod project you create. You

1. Open/Create your project. Let's call it "myMod"
2. Import the Vanilla Photobooth level.
   1. Click on File > New Level... > Levels Tab > Click on Show Inherited Levels (0)
   2. In the search box type SYS_CC_I
   3. Click on the Character Creation System_CC_I resource
   4. Press Select.
3. Move your hero onto the terrain
   1. Once your level has loaded, move your cursor on a part of the visible terrain.
   2. Press Ctrl+T
      This will move your hero onto the correct portion of the level.
4. Import Root Templates for your Visuals
   1. Open up your character visual file
   2. Look for the "Name" field. The "value" for that line will be codename of the visual followed by a 32 digit UUID:
      
   3. Copy the UUID, (if it doesn't exist grab the whole name)
   4. Search for it in BG3 Multi Modders Tool (Guide to using BG3MT Search).
   5. Look for the UUID occuring in a path that either has "Levels\***\Characters" or "Levels\***\Characters" or "RootTemplates".
      
   6. Open the LSX file.
   7. Look for the UUID / Name
   8. Create a new LSX file and only copy the GameObject that contains the UUID / Name (don't forget the preceeding tags)
   9. Save the LSX file in your mod while retaining the original file structure. For example, this one is in:
      Gustav\Mods\GustavDev\Levels\CTY_Main_A\Characters\_merged.lsf.lsx
      So you need to save it in:
      Data\Mods\myMod\Levels\CTY_Main_A\Characters\GameObjectUUID.lsx
   10. Name of the file should be the MapKey or ID of the GameObject.
   11. Convert the LSX to LSF using Convertor Tool.
5. Generate some portraits!
   1. Click on Project > Project Settings > Go to General Tab > Under Photo Booth Level, click the "..." and select the level you just imported(SYS_CC_I) > Save
   2. Click on Project > Render Character Portraits > Select "myMod"
   3. Click Render Portraits.
      Note: Selecting portrait rendering for other mods except "myMod" will not do anything. You have to set up a portrait generation level for EACH and EVERY mod that you want a portrait for. Once portrait is generated you can delete the level.

► older instructions

1. Open/Create your project. Let's call it "myMod"
   
2. Create a Dummy Level:
   1. Click on File > New Level... > New Level Tab > Basic_Level_A
   2. Give it a name, I'm calling it CustomPhotoBooth
   3. Click Create > Save
3. Extract Resources from the Vanilla Photobooth level.
   1. Click on File > New Level... > Levels Tab > Click on Show Inherited Levels (0)
   2. In the search box type SYS_CC_I
   3. Click on the Character Creation System_CC_I resource
   4. Press Select.
4. Extract Resources from the Vanilla Photobooth level.
   1. In the World Outliner click on the buttons as shown, to unselect these objects: Items, Sceneries, Decals, Terrain, Constructions, Global Entities.
      
   2. Hide the Terrain Folder (and probably the Scenery folder as well. I did)
      
   3. Expand all the folders inside the World Outliner window (Going from bottom folder to top is faster!)
   4. Now select everything. (Select All: Click the first item at the top, scroll to the very bottom, Hold Shift + Ctrl, and left click on the last item)
   5. Right Click on a file (not foler) > Create Prefab
   6. A CreateObjectWizard will pop up. Give it a Name. I'll call it "myPhotoBoothAssets"
   7. Ignore the errors & Save.
   8. File > Unload Level
5. Add Extracted Resources to your CustomPhotoBooth
   1. Click on File > Load Level > Levels Tab > Click on your Level (CustomPhotoBooth) that you made earlier > Click Select
   2. Locate your RootTemplates windows
   3. Click "Item View" tab
   4. Find your Project Name (in this case myMod) and click on it.
      
   5. myPhotoBoothAssets should appear on the right-hand panel.
   6. Drag and Drop it into the Game Window. You should see a dragonborn and a bunch of mannequins.
   7. Save https://f.rpghq.org/twEak7wD3rWL.png?n=pasted-file.png
6. Generate some portraits!
   1. [Legacy]If you edited characters using the old method, then you must also include each characters' RootTemplate / Levels file in:
      YourMod/Public/YourMod/RootTemplate/the_character's_roottemplate.lsf.lsx
      or
      YourMod/Mods/YourMod/Levels/the_character's_roottemplate.lsf.lsx
   2. Click on Project > Project Settings > Go to General Tab > Under Photo Booth Level, click the "..." and select the level you just made (CustomPhotoBooth) > Save
   3. Click on Project > Render Character Portraits > Select "myMod"
   4. Click Render Portraits.
      Note: Selecting portrait rendering for other mods except "myMod" will not do anything. You have to set up a portrait generation level for EACH and EVERY mod that you want a portrait for. Once portrait is generated you can delete the level.

[orinEsque]

Bypass "File Name too Long Error" in Windows
You'll need this if you are making custom changes to a mod you made using the toolkit

1. Search for Windows Powershell in your Start menu
2. Right Click and "Run as Administrator"
3. Paste in the following command (Source) to enable long file names:

   Code: Select all

   New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
   -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

[orinEsque]

VOICE MOD COMPATIBILITY SCRIPT

If you have a set of voice files that you want to override in bg3, and want the mod to be compatible with Larian's Mod Manager, then this python script automates the process.

Note: Only works for wem files that have a voiceid_handle.wem configuration. (wem files with just numbers as file names need something different that I haven't investigated)

REQUIREMENTS
You must unpack the following using bg3 multi modders tool:
(How to unpack BG3 game files)

1. Gustav.pak
2. Shared.pak
3. VoiceMeta.pak
4. English_Animations

INSTRUCTIONS

1. Put your custom wem files that will override in-game ones in a separate folder. Preferably in the structure:
   YourMod/Mods/YourMod/Localization/English/Soundbanks
2. Save the voice_overrider.exe file below.
3. Double click to run the script
4. Follow the instructions in the console window.

voice_overrider-v1.0.zip

Why is this an exe file? So trannies are forced to see this:

[Kowe]

How to use the Character Editor

Introduction

The Character Editor is responsible for the visual data of each character in the game, be it controllable or not.
It utilizes both Animation Rig data, 3D assets and textures. More about this later.
For this guide, Vemperen's Heads Repaired has been used for resource imports.

Preparation

Before we get to the Character Editor, a few preparations have to be made:

• Anything custom which will be imported has to be under the data path of "Baldur's Gate 3/Data/Public". Either use the Multitool to unpack a mod's pack and move its content there or make a new folder in Public, with your own creations copied there.
• Very Important: In the menu bar on top, under Preferences -> Global Settings -> Source Asset Data Path, set it to e.g. "C:/Program Files (x86)/Steam/.../Baldurs Gate 3/Data/". The exact path differs slightly, of course.

Importing Character Visuals and Models/Textures

► Show Spoiler

1. Before anything can be edited, the Character Visuals have to be overridden in the active mod, under the right-click menu on a resource. Go to the Resource Manager. Have "All" selected, above "Recents". Type in the character name in its search bar. Mind you, some NPCs have different file names from their in-game ones. To better find them only have the icon of two teapots (Character Visuals) checked/framed. 5th from right. For Astarion, it should look like in the example.
2. In this case, Astarion has to use a custom head armature. Click on the "Add Resource" button. The following window pops up afterwards:
   
   ► Show Spoiler

   
3. With the preparations from above, and since Astarion will use one of Vemperen's heads, click on Model to import a head armature. A File Explorer window will pop up for it, navigate to where the specific head's .GR2 files are located, it should be two of them. Once selected, the window appears. Feel free to give it a name which makes it easy to distinguish and find. Click on Ok. A new window appears next:
   
   ► Show Spoiler

   
4. It is a non-textured head model. Click on Import. Once it is finished and back to the Resource Manager, the custom resource will appear in the list of resources of the active mod. In the Baldur's Gate 3 Data folder, it appears both under Processed and Public/ProjectName/HeadName.
5. For Textures it is a similar process, so follow the same steps but select the texture after having clicked on the Texture button in the Resource Wizard. This applies to any kind of texture, not only CLEA, HMVY, BM, or at least any that is utilized for character models.

Using the Character Editor

1. When everything has been imported, double-click on the Character Visual resource to be edited. A new window pops up and it looks like this:
   
   ► Show Spoiler

   
2. Let's go over the menu bar first. Under File: Open Character Visual, Close, Save, Save All, Load Preset, Save Preset. One small remark, a character's visual data can be saved as a preset and loaded in other files. Makes it easier for mass-editing. Under Edit: Undo, Redo, Remove Unused Resources. The last one is particularly good for removing any deleted imports not accessible anymore. Under View: Properties Explorer, Body Editor. These two are of utmost importance. In the middle of the screen is the Character Preview.
3. Now, for anyone familiar with changing NPC Visuals, things will be easier to handle. Otherwise, this tutorial here is a recommended read.
4. The Body Editor contains both the BaseVisuals as Rig Type and BodySetVisuals as Visuals. The Editor itself handles it well in that only certain Visuals are available to a Rig Type, so it is sorted already. No NPC has either of them set in stone, so they can be freely changed. Beneath those two, anything what is listed under "Slot" nodes in the .lsx code, is available. An important distinction: Body doesn't mean a character's body, but equipment slots for it, be it a chest armor or some kind of pants. They are also limited by the Rig Type and Visuals, so female armor cannot be selected for male characters under All Visuals, under the search bar. Here are the available Slots:
   
   ► Show Spoiler

   
5. As for the Properties Explorer, meshes and textures are found under "Override Parameters". Any materials selected in the Body Editor can be found here. So Head, Body (not Equipment!), Armor pieces, Wings, Hair, it can be found here. Each texture can be modified with various parameters and textures can be chosen for each mesh. The former can be seen in the image under key point 1 of this paragraph, the latter with this image:
   
   ► Show Spoiler

   
6. As an example, two more images will be provided, but first some information. If any material is missing a texture it will show up as what is names as "Engine_Default_Mesh_Lit_Opaque". There are also textures which can be defined as "global" textures, meaning they aren't sparsely used on just one character, but widely. SHARED_LashShadow and the other three SHARED_ textures in one of the next two images are such. Play around with them, but not every texture will apply well on each type of material/model. Anyway:
   
   ► Show Spoiler

   
   ► Show Spoiler

   
7. Under Presets are all the MaterialPresets from the code and the Parameters. There are only Scalar, Vector2, Vector3, Vector (technically Vector4), Texture and VirtualTexture parameters which can be found here. The latter two are of no importance here. Every other parameter has one to four float (decimal) values, with Scalar having one and Vector having four. As with the Override Parameters, play around with the Presets. A tip, there are presets available under each Preset. To give an example, 06Eyes and the various eye colors in the Character Creation menu.
8. When all is done, do not forget to save under File! The Toolkit should ask if you if you want to save if you didn't, though.

Root Templates

1. To get the new Character Visual working, the mod requires a RootTemplate file. Even more data with imported resources, but more about this below. The Root Templates follow the same procedure as other resources under the resource manager, but this time Root Templates window below the Manager is utilized. All of them can be found under these four: Gustav, GustavDev, Shared, SharedDev. Use the window's search bar to find the right file. Right-click on it and click on "Override in Active Mod".
2. Navigate to the Resource Manager, select the RootTemplate in the mod. In the sidebar to the left, is all the information necessary. Of most importance are EquipmentClass and ParentTemplateID. They have to be the correct ones for the new Rig Type and Visuals. So, for example, if it is an elf, it has to be the equipment class for elves and, in case of Astarion, Elves_Female_Players or something like this for ParentTemplateID.
3. Small remark again: I did this manually and haven't utilized the Toolkit for RootTemplates. So this may or may not work. A UUID should be provided with the RootTemplate in the Toolkit so it can be looked up via the Multitool search feature and be created manually, then moved to the mods RootTemplate folder. Which should be under Data/Public/ProjectName.

Further Requirements for Custom Heads

In case of custom resources, there is often more data which has to be imported to the mod. In the case with my mod of Astaria, SkeletonBank, MaterialBank, AnimationBank, AnimationSetBank, AnimationBlueprintBank. TextureBank in case for any imported textures. A quick rundown of the purpose of them. And a disclaimer again, I did this manually and haven't utilized the Toolkits features for these banks. In case of Vemperen's Heads, the .lsx file was found under Data/Public/vemperens_heads/Content/[PAK]_vemperens_heads, as it has been moved to the Baldur's Gate 3 folder. Which is necessary, to my knowledge. The banks copied from it are in green:

1. SkeletonBank: Anyone who has taken a look at i.e. a head armature in Blender has noticed its bones aka skeleton. They are responsible for the correct form of the model.
2. MaterialBank: Forgot what it is again for, but it it uses common files.
3. AnimationBank: Facial Expressions.
4. AnimationSetBank: Contains IDs of the AnimationBank resources and then corresponding Mapkeys for Blueprints and Head Assets.
5. AnimationBlueprintBank: Genomes. IK nodes and their rigging. Foundational code stuff. It can be accessed via the Genome Editor in the Toolkit, but this is for another guide in the future.

Setting up the Banks

While the Toolkit allows to access these banks, I haven't tried out using the option. So, for the manual method, along with trouble-shooting, here are a few things that require to be done before the mod shows the custom head properly in-game:

1. SkeletonBank ID from the custom head has to be the UUID for SkeletonResource in both VisualBank and AnimationBank.
2. Bounds Min and Bounds Max have to be copied from the mod the head armature is from. Found under VisualBank.
3. Same with AnimationSetOverrides and AnimationWaterfall nodes. Copy them from the head armature mod to the VisualBank.
4. BlueprintInstanceResourceID under VisualBank has to be taken from the AnimationBlueprintBankID of the head it replaces. In case of Astaria, to give an example, it is from ELF_M_Head_Astarion, or something similar. Found under either Gustav or Shared and their Content folder.

FAQ

• Help! The eye mesh disappears when zooming towards the character's head in the Character Editor! - Just an issue of the Toolkit, it displays normally in-game if everything else has been done properly.
• Help! The head is stretched and deformed! The eyes and face is set in front of the head! - SkeletonBank issue.
• Help! The head is shown and animated, but looks deformed or has wrong proportions! - Do not use AnimationWaterfall nodes from other heads. Only the custom/imported one.
• Help! The had is floating above the body, with empty space between the chest and neck! - I forgot the exact reason, but it may be AnimationBluepringBank or Min/Max bounds under VisualBank.

To-Do List

• Import models for other slots and see how it differs from using a custom head for a mod.