bg3-mod-helper: A Visual Studio Code Extension for Baldur's Gate 3 Modding

IF UNABLE TO PACK MOD OR CONVERT TO LOCA IS NOT WORKING, ENSURE LSLIB.DLL IN YOUR DIR THAT CONTAINS DIVINE.EXE IS UNBLOCKED IN ITS PROPERTIES.

Introducing bg3-mod-helper, a Visual Studio Code extension that I created to help mod developers in the Baldur's Gate 3 community. This tool was made to streamline your modding workflow, making it more efficient and less time-consuming.

IMPORTANT: I AM ASSUMING MOST OF YOU HAVE ALREADY BEEN MODDING SO YOU WILL HAVE THE DIVINE.EXE DOWNLOADED AS WELL AS HAVING LSLIB.DLL UNBLOCKED AND IN THE CORRECT LOCATION. PYTHON IS ALSO REQUIRED FOR SOME ASPECTS OF THE TOOL AS WELL AS A FEW EXTERNAL MODULES LIKE PIL AND NUMPY. THE EXTENSION WILL PROMPT YOU TO DOWNLOAD IF IT CANT FIND (I MAY HAVE MISSED SOME CHECKS IN WHICH CASE IT WILL JUST ERROR OUT, WILL NEED TO TEST TO FIND OTHER IMPORT LOCATIONS)

Key Features:

• UUID and Handle Generation: Easily generate UUIDs and handles with a simple right-click in your workspace (control shift u and control shift h will also spawn uuids and handles respectively).
• Hover over functions to get information on their parameters (still in beta, looking for help collecting function parameters information)
• Instance Finder: Quickly locate where a UUID or handle is used in your project with a handy tooltip that appears when you hover over an identifier.
• Quick Navigation: Right-click on a UUID or handle to access a list of files where it's used. This allows you to jump directly to any instance for editing or review.
• .loca.xml File Integration: Automatically updates .loca.xml files with new handles, creating blank entries for seamless integration.
• Generate file templates from right clicking on file explorer and clicking "Create BG3 File" which will display a drop-down of file templates to create, which can be filtered by typing (limited selection as I slowly add in more of these and more functions, if you urgently want one, please message me)
• If you have an internet connection, right click in the editor and hover over the export tools to access the stats/lsx validator tools and search tool in visual studio. (If you click it while having text highlighted it will autocopy the text so you can easily paste as well)
• By specifying "< !--press control shift a to quick spawn a line below" and "end custom attribute lines-->" as well as "< !--press control shift 2 to quick spawn a line below" and "end ctrl shift 2 clipboard-->" (remove the space before the !), you can use their respective commands to quickly get a dropdown of items between the rows, which helps quick add lines. Some templates come with it, looking to the community for help filling them all out with all their respective attribute lines. Control shift 2 is just there as a bonus clipboard for you.
  

• Right clicking on a a dds or png image will allow you to convert that image to the opposite (dds->png or png->dds) Also allowed for resizeing of png/dds images.
• Pressing the left side icon (looks like a box that says b3) opens a menu that lets you do a couple of quick actions which are as followed:
  

• Pack your mod directly in visual studio code and have it sent to the mods folder.
• Launch the game directly from visual studio (working on removing the launcher)
• Convert all your xml localization files to loca files
• Create an icon atlas, its corresponding .dds, and its corresponding merged.lsx. You need to provide a directory of icons you wish to have added to the atlas and .dds.
  

Installation and Usage:
Install bg3-mod-helper through Visual Studio Code (View -> Extensions -> ‘...’ -> Install from VSIX). Once installed, access its features through the command palette or the editor's context menu (right clicking). When first opened, a .vscode folder will be made in your workplace with a settings.json. This sets your root mod path, you can delete before you pack or leave. It wont affect much. You can also hide the folder in vscode if it bothers you being there.

If you are having trouble, I finally added the mod onto the marketplace so you can install opening extensions and searching bg3_mod_helper to find my extension.

To adjust settings, click the popup that I made appear on the bottom right when visual studio launches showing the extension is working as it has a button to jump straight to settings of the bg-mod-helper extension. You can also enter ctrl and , to open the settings and search bg3-mod-helper, it should appear. Or just open visual studio code settings normally.

You can now have multiple mods in the same workspace but when you hover it will only look for uuids/handles in that folder and its subfolders. If you want multiple mods to be searched when hovering, move the mods in your workspace into one location but be sure to change your root mod (in workplace, not users) to point to the mod that you actually want to pack in your workplace.

If you have an internet connection, right click in the editor and hover over the export tools to access the stats/lsx validator tools and search tool in visual studio. (If you click it while having text highlighted it will autocopy the text so you can easily paste as well). I did not make the validator tools, they were made by norbyte. Please route any questions for it to the bg3 modding discord.

I should really add some images here or info on how the mod works :)

Recent Updates (2/27/2024):
Patch 1.0.0

• Icon atlas can now be generated as well as its corresponding .dds and merged.lsx file. You need to provide a directory of icons and it will take those icons and put them on the .dds texture for the atlas as well as update your atlas on the location of where the images are placed.
• Image conversion (png<->dds) as well as resize png/dds images.
• ALOT of refactoring to have code nicer and tidey to release. My tests show everything working so far but expecting bugs and will be monitoring.
  

Patch 0.9.999

• Can now convert merged files to lsf, works with icon atlas now, didnt before
• Add delay to allow proper conversion before packing (was requiring a double pack before, sorry for any confusion it caused)
• Mods folder is now looked for when searching for a meta, not Mods/modname. Uses the name of the first folder in there as the mod name and will look in it for meta.lsx
• Moved create bg3 file lower so handles and uuid is up top 
  

Patch 0.9.997

• Can now convert merged files to lsf files. Will autoconvert when packing mod
  

Patch 0.9.996

• More cleanup and tidying of folders/files for a smooth launch
• Delete .vscode folder so it doesnt get packed and recreate after packing
• fix gotouuidhandle via right click (was broken)
  

Patch 0.9.995

• Functions can be hovered over for information on what they do and their parameters. Still working on collecting more functions, have added in a few so far.
• Auto set root mod folder correctly so its not global (fixed it from swapping folders if you opened a new window). DO NOT CHANGE THE ROOT MOD FOLDER SETTINGS FOR USER, CHANGE THEM FOR WORKSPACE IN THE SETTINGS.
  

Patch 0.9.992

• Auto set mod folder when opening visual studio code based of set workplace. If working with multiple mods in one workspace, be sure to change this to your main mod folder that you want to pack.
• Testing function hovers, dont worry about it for now
  

Patch 0.9.989

• No more searching on all words. Uuid and handle patterns more strict, fixing performance by removing unnecessary and accidental search's on non uuid's and handles.
• Proper usage of maxfilesreturned so stops searching when max file limit is reached rather than searching all and then cutting via maxfiles
  

Patch 0.9.989

• Formatting fixes for hover
• Proper display of lines for certain special lines
  

Patch 0.9.988

• Will now allow you to autoconvert all xml files in your Localization folder (and subfolders) to .loca files, allowing for multiple language folders essentially. Can no longer convert loca to xml but will add that in again later as its not as important atm.
• New setting to allow single file loca conversion should you only need to alter one file for some reason.
• Search page now retains data if you leave the tab (previously refreshed the tab, losing results)
  

Patch 0.9.985

• The debug update, minor real changes, mostly adding proper logging to help users with issues.
  

Patch 0.9.980

• Removal of workspace setting. Auto using vs code workspace. If you want to have multiple mods in one workspace, you should create one folder with all your mods inside that you want to be searchable when looking for instances. Then, the main mod you are working on in that workspace should be what you make as your root mod folder. 
• Optimization fixes, hopefully fixing lag issues. Testing needed.
• Refactor for future, way more modular and hoping future updates will roll out faster now.
• Settings update dynamically now, no more restarts of vscode required.
• Backend logic fixes.
• Autopack and convert localization files one button. Please ensure you only have either one xml or one loca file in your mods Localization folder/subfolder. (You can have 1 loca and 1 xml, i mean you cant have something like 0 loca and 2 xml or 2 loca and 1 xml). Change any .loca.xml files to jus .xml if you have issues as well.
  

Patch 0.9.951

• Pressing the left side icon (looks like a box that says b3) opens a menu that lets you do three things currently. You can launch the game, convert xml to loca file, or pack your mod. Make sure you specify your mods root folder as well as the location of your divine.exe. PYTHON REQUIRED TO WORK AS WELL AS EXPORT TOOLS. NOT WELL TESTED YET
• Merged template added
  

Patch 0.9.930

• By specifying "< !--press control shift a to quick spawn a line below" and "end custom attribute lines-->" as well as "< !--press control shift 2 to quick spawn a line below" and "end ctrl shift 2 clipboard-->" (remove the space before the !), you can use their respective commands to quickly get a dropdown of items between the rows, which helps quick add lines. Some templates come with it, looking to the community for help fillign them all out with all their respective attribute lines. Control shift 2 is just there for fun, maybe you can find use for it.
  

Patch 0.9.920

• Decent amount of refactoring for the future
• More templates added
• Updated patch versioning, using triple digits moving forward, sorry for confusion before this if patch/change logs are out of order
  

Patch 0.9.901

• Added more file templates and greatly fixed how it works, can filter search now. Easier to add future templates now as well
• More templates and template format fixes
  

Patch 0.9.81

• You can now use the export tools (stats validator, lsx validator, search engine) in a visual studio tab for ease. Will copy your highlighted text if you have something highlighted when you press one of the tool, for easier use
• bug fixes and dumb mistakes by me
  

Patch 0.9.71 (No reason for worry but should be tested more due to trying to fix performance)

• Better root mod folder integration. You can now have multiple mods in the same workspace but when you hover it will only look for uuids/handles in that folder and its subfolders. If you want multiple mods to be searched when hovering, move the mods in your workspace into one location and make that location folder your root.
• Formatting hover for better readability and usage
• fix go to action (was not working :p)
• caching for uuids/handles to stop rapidswapping on hovers
• less resource intensive (it already wasnt) and accounting for memory leaks. Performance fixes, need to be wary about this update incase I made a memory leak while trying to secure it :p
• autohighlight uuid/handle when you go to uuid/handle
• changed text on instance not found for clarity
  

Patch 0.9.6

• Can now use keyboard shortcuts to spawn uuids and handles (uuids: 'control + shift + u', handles: 'control + shift + h')
  

Patch 0.9.55

• Create a new right click menu button when clicking on the file explorer, Create BG3 File, that when hovered over will display template files that the user can click to rapidly make a new mod file (limited options atm, adding more soon)
• hotfix 5 moved create bg3 file button so its below create file and create folder since those would be used more i guess
  

Patch 0.9.4

• Changed insert to generate on right click menu
• Added settings for extension
• Can limit amount of lines showing in hover by accessing settings
• Can now use multiple mod project directories in a workspace and generate handles without adding into multiple .loca.xml files. Will only update the project folder for the mod you added the handle into.
  

Full Release Information:
Your Feedback Matters! This is the first official non beta version I have released for this. While I have tried to iron out what I can, adding in new features while simultaneously cleaning up alot of dead and confusing code can always lead to unexpected issues so im hoping to get some good bug reports if something is wrong :). I also still need help collecting function information as wel as file templates so feel free to help! I'm eager to hear from you! Share your experiences, suggestions, and any issues directly via discord: my discord id to dm me directly

Reach Me/Help:
For general modding guidance and resources, check out my bg3 modders wiki or the community library wiki. The bg3 modding wiki is a good source of information as well.
DM me on discord or on this mod page itself if you have any questions, bugs, or requests.

Lots of thanks and appreciation to those who tolerated my questions as I tried to figure out different aspects of this extension since its my first time making something like this! While they have no actual affiliation to this mod, the resources and answers they provided to my questions were eye opening. Also alot of functionality I learned from looking at how LaughingLeader setup python scripts to use divine.exe and lslib.dll. Thank you all again and thank you to the community for giving me useful feedback!