shresht7/vscode-bg3-modding

A VSCode extension with tools, snippets and helpers for modding Baldur's Gate 3

BG3 Modding support for Visual Studio Code

This VS Code extension contains useful tools, snippets and helpers for creating mods for Baldur's Gate 3.

Table of Contents

• ⚡ Activation Events
• ⭐ Features
  • 📄 Snippets
  • ⌨️ Commands
    • Generate UUID
    • Generate Handle
    • Copy Mod UUID
    • Convert Version Number
    • Bump Version Number
  • ✅ JSON Validation
  • ⚙️ Default Configurations
    • files.associations
    • search.exclude
• ⚙️ Extension Settings
• 📄 License

⚡ Activation Events

• workspaceContains:/**/meta.lsx

  The extension activates for a workspace that contains the meta.lsx file.

⭐ Features

• 📄 Snippets
• ⌨️ Commands
• ✅ JSON Validation
• ⚙️ Default Configurations

📄 Snippets

The extension contributes the following snippets:

Name	Activation	Description
BG3 UUID	uuid	Generate a random UUID
BG3 Handle	handle	Generates a random UUID handle used in localization files
Ext.Utils.Print()	print, eup	Ext.Utils.Print()
Ext.Osiris.RegisterListener()	rl, orl, eorl	Ext.Osiris.RegisterListener()
Override Stat Entry	new, override	Create an override for an existing Stat Entry
Script-Extender Config	cfg, Config.json	Generates the boilerplate Script-Extender Config.json
meta.lsx	meta	Generates the boilerplate template for meta.lsx

Back to Top ⬆️

⌨️ Commands

The extension contributes the following commands:

• Generate UUID
• Generate Handle
• Copy Mod UUID
• Convert Version Number
• Bump Version Number

Generate UUID

Generate a random UUID and insert at the current selection.

b7b98e25-ff34-40dd-b019-ab25521ae5a0

Generate Handle

Generate Handle and insert at the current selection.

hb7b98e25gff34g40ddgb019gab25521ae5a0

Copy Mod UUID

Copies the Mod's UUID to the clipboard.

Convert Version Number

Convert between BG3 version numbers.

1.0.0.0 --> 36028797018963968
36028797018963968 --> 1.0.0.0

Input: Version Number

Takes the version number as input in either the string format (e.g. 1.0.0.0) or bigint format (e.g. 36028797018963968).

Bump Version Number

Bumps the version number in the meta.lsx by the specified type.

1.0.0.0 --- Bump Minor Version --> 1.1.0.0
1.2.0.7 --- Bump Major Version --> 2.0.0.0

Input: Kind

• Major
• Minor
• Revision
• Build

Back to Top ⬆️

✅ JSON Validation

The extension contributes JSON validation schemas for:

• ScriptExtender/Config.json
• ScriptExtenderSettings.json

This will enable intellisense and provide validation for these files.

Back to Top ⬆️

⚙️ Default Configurations

The extension provides default configuration settings for:

files.associations

"files.associations": {
    "*.lsx": "xml",
    "*.lsj": "json"
},

search.exclude

"search.exclude": {
    "**/*.raw": true,
    "**/Story/*.div": true,
    "**/*.osi": true,
    "**/*.dat": true
}

Back to Top ⬆️

---

⚙️ Extension Settings

Include if your extension adds any VS Code settings through the contributes.configuration extension point.

For example:

This extension contributes the following settings:

• myExtension.enable: Enable/disable this extension.
• myExtension.thing: Set to blah to do something.

Back to Top ⬆️

---

📄 License

This project is licensed under the MIT License.

vscode-bg3-modding's Issues

Refactor: Consolidate regular expressions

Regular expressions (like UUID and Handle) are peppered throughout the code. Consider just how many times they are used; it might be wise to define them in one place. (and have tests!)

Setup Configuration ⚙️

Create a manager to handle vscode configuration stuff.

Provide XML Schema Validation

Provide XSD Schema files for the various XML files.

• meta.lsx
• Localization XMLs
• modsettings.lsx

Create command: `Copy Mod UUID to clipboard`

Create a VS Code command to copy the Mod's UUID to the clipboard.

Contribute `configurationDefaults`

Contribute default configuration settings like:

{
    // Create file associations for Larian Studios specific files
    "files.associations": {
        "*.lsx": "xml",
        "*.lsj": "json"
    },
    // Tells the VS Code search to ignore Osiris compiled files
    "search.exclude": {
        "**/*.raw": true,
        "**/Story/*.div": true,
        "**/*.osi": true,
        "**/*.dat": true
    }
}

Add `IDEHelpers`

Add the IDEHelper references.

The infrastructure to provide Lua reference files is set, all I need to do is to put in the actual IDEHelper files.
See #27 for more context.

Update categories in `package.json`

vscode-bg3-modding/package.json

Lines 13 to 16 in 8e9c93b

	"categories": [
	"Snippets",
	"Other"
	],

Add commands to generate UUIDs and Handles

Add VSCode Commands to generate UUIDs and BG3 Handles

Create configuration settings to selectively enable/disable features

Allow the user to selectively enable/disable the features provided by the extension.

This can be a simple if block surrounding the initializer for that feature when activating the extension. May have to figure out how to "activate"/"deactivate" a feature if the setting is changed (without having to restart the extension).

Add JSON Schema Validation

Create JSON Schema validation for:

• Script-Extender Config.json
• meta.lsx
• ScriptExtenderSettings.json?

Bug: Duplication in Lua configuration settings

vscode-bg3-modding/src/configs/Lua.ts

Lines 36 to 38 in 3ebff0a

	const settings = this.config.get<T[]>(section) || [];
	settings.push(...items);
	this.config.update(section, settings, this.configurationTarget);

This causes duplication on successive calls. Consider using Set here.

Create shortcut command to important folders

Create a command to open relevant folders in the explorer.

• Game Folder (requires the user to provide the path to their installation)
• Larian Studio's AppData Folder.

Create snippets for Stat Entries

Create snippets to generate stat entries in stats files.

for example, override to generate something like this:

new data "$1"
type "SpellData"
using "$1"
data $0

or new for the entire thing:

new data "$1"
type "SpellData"
data ...
data ...
data ...

Add GitHub Actions: Tests

Create a workflow to run automated tests.

Setup Tasks Provider

Setup Tasks Provider so that tasks can be registered to VS Code.

Change urls to the `main` branch

vscode-bg3-modding/package.json

Lines 69 to 82 in 0cdce77

	"xml.fileAssociations": [
	{
	"pattern": "**/meta.lsx",
	"systemId": "https://raw.githubusercontent.com/Shresht7/vscode-bg3-modding/xsd/Schema/meta.lsx.schema.xsd"
	},
	{
	"pattern": "**/Localization/**/*.xml",
	"systemId": "https://raw.githubusercontent.com/Shresht7/vscode-bg3-modding/xsd/Schema/localization.xml.schema.xsd"
	},
	{
	"pattern": "modsettings.lsx",
	"systemId": "https://raw.githubusercontent.com/Shresht7/vscode-bg3-modding/xsd/Schema/modsettings.lsx.schema.xsd"
	}
	],

The xsd branch no longer exists, change the schema urls to point to the main branch instead.

Register hover provider for localization text and handles

When hovering over a localization handle, show the corresponding translated text.

Provide IDEHelpers

Providing IDEHelpers with the extension will eliminate the need to manually download them and set the Lua.workspace.library.

Something like this should work:

const setting = vscode.workspace.getConfiguration().get("Lua.workspace.library") as string[];
setting.push(path.join(context.extensionPath, "References"));
vscode.workspace.getConfiguration().update('Lua.workspace.library', setting, vscode.ConfigurationTarget.Workspace);

where References is a folder containing the IDEHelpers in the extension root path.

Update documentation

Update the documentation

• README.md
• CHANGELOG.md

Parse `meta.lsx` for Mod metadata

lsx (xml) files are common when working with BG3 mods. Sooner or later we'll need a proper xml parser (instead of the usual regex shenanigans).

Starting with meta.lsx for the mod metadata sounds like a good idea.

Add commands to parse and generate version numbers.

Create vscode commands for version numbers.

Add hover widget for version number in `meta.lsx`.

When hovering over the int64 version number in the meta.lsx file, the extension should parse the number and show the string equivalent.

Create "bump version number" command

Create a command to bump the version number in the meta.lsx file.

Consolidate `meta.lsx` related logic

Because of 9dca9ac, bumpVersionNumber command now fails as it cannot find the lsx version regex. I can point it to the VersionHoverProvider but this will need a proper solution eventually.

Originally posted by @Shresht7 in #35 (comment)

meta.lsx code is all over the place. It should probably be consolidated.

Add support for version numbers

• #14
• #13

Fix: Broken Links

Links here are broken! (all because of the emojis! 😡)

vscode-bg3-modding/README.md

Lines 38 to 46 in 19e8a38

	- [Snippets](#snippets)
	- [Commands](#commands)
	- [`Generate UUID`](#generate-uuid)
	- [`Generate Handle`](#generate-handle)
	- [`Convert Version Number`](#convert-version-number)
	- [JSON Validation](#json-validation)
	- [Default Configurations](#default-configurations)
	- [`files.associations`](#filesassociations)
	- [`search.exclude`](#searchexclude)