### Example: Replace Main Menu Start Game Action
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/test/SE_API.md
Demonstrates registering a wrapper type for the main menu DataContext and setting a handler for its StartGameCommand. This example shows how to intercept and modify existing UI interactions.
```lua
-- Register a wrapper type for the main menu DataContext
Ext.UI.RegisterType("SAMPLE_MainMenuCtx", {
StartGameCommand = {Type = "Command"} -- builtin command to start game
}, "gui::DCMainMenu") -- gui::DCMainMenu is the name of the ingame main menu DataContext
-- Jank sample code for getting a widget, DON'T DO IT LIKE THIS!
local mainMenu = Ext.UI.GetRoot():Find("ContentRoot"):VisualChild(1)
-- Create a wrapper around the original main menu DataContext
local ctx = Ext.UI.Instantiate("se::SAMPLE_MainMenuCtx", mainMenu.DataContext)
ctx.StartGameCommand:SetHandler(function ()
print("do stuff")
end)
-- Overwrite datacontext with our wrapper
mainMenu.DataContext = ctx
```
--------------------------------
### Modding Environment Setup and Folder Layout
Source: https://context7.com/bg3-community-library-team/bg3-community/llms.txt
Lists required tools and recommended folder structure for BG3 modding. Ensure all listed tools are downloaded and installed.
```text
Required tools:
- Visual Studio Code: https://code.visualstudio.com/download
- BG3 Mod Manager: https://github.com/LaughingLeader/BG3ModManager/releases
- BG3 Modders Multitool: https://github.com/ShinyHobo/BG3-Modders-Multitool/releases
- LSLib / Export Tool: https://github.com/Norbyte/lslib/releases
- (Pre-Patch 7 only) Mod Fixer: https://www.nexusmods.com/baldursgate3/mods/141
Recommended folder layout:
bg3_mods/
├── bg3-modders-multitool/ (shortcut at root)
├── BG3ModManager_Latest/ (shortcut at root)
└── ExportTool-v{version}/ (shortcut at root)
Mods folder (for .pak files):
%LocalAppData%\Larian Studios\Baldur's Gate 3\Mods
```
--------------------------------
### Example Inspiration Framework JSON Configuration
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Mod-Frameworks/using-inspiration-framework.md
A concrete example of the JSON structure for registering a custom background and a goal.
```json
{
"FileVersion": 1,
"Backgrounds": [
{
"Name": "AGTT_BS_Apprentice",
"Id": "ecb6ee29-5805-474b-9eb7-1d5ee7b89eba",
"Goals": [
{
"Name": "Act1_AGTTBS_Apprentice_DivinityUndone",
"Id": "261cf8cb-a978-4560-b8f4-9db43a734509"
}
]
}
]
}
```
--------------------------------
### Test Loading Setup
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/dribblespec.md
Example of an init file that explicitly requires other test files. This is necessary because DribbleSpec does not auto-discover tests.
```lua
-- Shared/MyMod/Tests/_Init.lua
Ext.Require("Shared/MyMod/Tests/Smoke.test.lua")
Ext.Require("Shared/MyMod/Tests/Runtime.test.lua")
```
--------------------------------
### Example Tutorial Chest Item Distribution
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/General/Shipping-Items-to-Users.md
This example shows how to add one modded item and ten vanilla items to the Tutorial Chest.
```txt
new treasuretable "TUT_Chest_Potions"
CanMerge 1
new subtable "1,1"
object category "I_Aethers_Black_Dye",1,0,0,0,0,0,0,0
new subtable "10,1"
object category "I_OBJ_Camp_Pack",1,0,0,0,0,0,0,0
```
--------------------------------
### Bootstrap Lua Script Example
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Mod-Integration/BG3SX/Whitelisting.md
Add a simple print statement to your BootstrapServer.lua file to verify that the script is loaded correctly when the game starts.
```lua
print("MyModName has been loaded succesfully")
```
--------------------------------
### Install .NET Desktop Runtime
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tools/LSLib-Macosx-Linux.html
Installs the Windows version of the .NET Desktop Runtime using Wine. This is a prerequisite for running LSLib tools.
```bash
wine windowsdesktop-runtime-8.0.14-win-x64.exe
```
--------------------------------
### Example of Completing a Goal
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Mod-Frameworks/using-inspiration-framework.md
An example demonstrating how to call the `CompleteGoal` API with specific mod, goal, and character identifiers.
```lua
{
modGuid = "33d8dcef-c9e2-4e19-9a90-86f6e35d065a",
Goals = {
Act1_AGTT_BS_Apprentice_TestGoal = {
GoalId = "fc8b0dcc-01fc-4d18-818e-457f37a2516b"
CharacterId = "Elves_Female_High_Player_39cda0f1-b0e1-15c9-a896-3bd8f0abb6ae",
}
}
}
```
--------------------------------
### Define Quickster Starting Equipment
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Classes/Basic-Class-Creation.md
This snippet defines the starting equipment for the 'Quickster' class in Equipment.txt. It includes weapons, healing potions, armor, and utility items.
```cpp
new equipment "EQP_CC_Quickster"
add initialweaponset "Melee"
add equipmentgroup
add equipment entry "WPN_Dagger"
add equipmentgroup
add equipment entry "WPN_HandCrossbow"
add equipmentgroup
add equipment entry "OBJ_Potion_Healing"
add equipmentgroup
add equipment entry "OBJ_Potion_Healing"
add equipmentgroup
add equipment entry "ARM_Robe_Body"
add equipmentgroup
add equipment entry "ARM_Boots_Leather"
add equipmentgroup
add equipment entry "OBJ_Scroll_Revivify"
add equipmentgroup
add equipment entry "OBJ_Keychain"
add equipmentgroup
add equipment entry "OBJ_Bag_AlchemyPouch"
add equipmentgroup
add equipment entry "ARM_Camp_Body"
add equipmentgroup
add equipment entry "ARM_Camp_Shoes"
add equipmentgroup
add equipment entry "OBJ_Backpack_CampSupplies"
```
--------------------------------
### Example: Registering a Stealth Kobold Spawn Template
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Mod-Integration/More-Firewine-Kobolds.md
This example demonstrates registering a new spawn template named 'StealthRangerKobold' with specific statuses like INVISIBLE and HASTE.
```lua
-- Register a new spawn template for a stealth kobold
Mods.MoreFirewineKobolds.API.RegisterSpawnTemplateDef("StealthRangerKobold", {TemplateID = "1ad1fdb1-ea7f-492d-a72a-e282d9965b47",Quantity = { fixed = 1 },Statuses = { "INVISIBLE", "HASTE" }})
```
--------------------------------
### Example Vendor Inventory Item Distribution
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/General/Shipping-Items-to-Users.md
This example demonstrates adding a modded item to Arron's inventory and vanilla items to Dammon's.
```txt
new treasuretable "DEN_Entrance_Trade"
CanMerge 1
new subtable "1,1"
object category "I_Aethers_Black_Dye",1,0,0,0,0,0,0,0
new treasuretable "DEN_Weaponsmith_Trade"
CanMerge 1
new subtable "10,1"
object category "I_OBJ_Camp_Pack",1,0,0,0,0,0,0,0
```
--------------------------------
### Define Class Starting Equipment
Source: https://context7.com/bg3-community-library-team/bg3-community/llms.txt
Configure the starting gear loadouts for a class. This text file lists equipment groups and individual items.
```cpp
// Public/Quickster/Stats/Generated/Equipment.txt
new equipment "EQP_CC_Quickster"
add initialweaponset "Melee"
add equipmentgroup
add equipment entry "WPN_Dagger"
add equipmentgroup
add equipment entry "WPN_HandCrossbow"
add equipmentgroup
add equipment entry "OBJ_Potion_Healing"
add equipmentgroup
add equipment entry "OBJ_Potion_Healing"
add equipmentgroup
add equipment entry "ARM_Robe_Body"
add equipmentgroup
add equipment entry "ARM_Boots_Leather"
add equipmentgroup
add equipment entry "OBJ_Scroll_Revivify"
add equipmentgroup
add equipment entry "OBJ_Keychain"
add equipmentgroup
add equipment entry "OBJ_Bag_AlchemyPouch"
add equipmentgroup
add equipment entry "ARM_Camp_Body"
add equipmentgroup
add equipment entry "ARM_Camp_Shoes"
add equipmentgroup
add equipment entry "OBJ_Backpack_CampSupplies"
```
--------------------------------
### Example: Adding a Spawn Template Entry to a Region
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Mod-Integration/More-Firewine-Kobolds.md
This example shows how to add a new entry to the 'WLD' region, referencing the 'StealthRangerKobold' spawn template with a weight of 25.
```lua
-- Add a new entry to a region using a spawn template
Mods.MoreFirewineKobolds.API.AddRegionEntry("WLD", {
SpawnTemplate = "StealthRangerKobold",
Weight = 25
})
```
--------------------------------
### Install VSCode Extension via Command Palette
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/ScriptExtender/GettingStarted.md
Manually install the BG3-SE-Snippets extension in VSCode by pasting the provided command into the command palette (Ctrl+P).
```bash
ext install FallenStar.bg3-se-snippets
```
--------------------------------
### Example: Changing an Existing Entry's Weight
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Mod-Integration/More-Firewine-Kobolds.md
This example shows how to change the weight of an existing entry in the 'WLD_Main_A' region, identified by the key 'DrunkKobold', to 40.
```lua
-- Change the weight of an existing entry
Mods.MoreFirewineKobolds.API.SetEntryWeight("WLD_Main_A", "DrunkKobold", 40)
```
--------------------------------
### Example: Adding an Inline Entry to a Region
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Mod-Integration/More-Firewine-Kobolds.md
This example demonstrates adding an inline spawn entry directly to the 'SCL' region, specifying template ID, quantity, statuses, and weight.
```lua
-- Add an inline entry directly to a region
Mods.MoreFirewineKobolds.API.AddRegionEntry("SCL", {
TemplateID = "22fc3ef8-64f0-4298-a598-03fbc9dfb9aa",
Quantity = { fixed = 1 },
Statuses = { "WILD_MAGIC" },
Weight = 15
})
```
--------------------------------
### Assign Starting Equipment to Class
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Classes/Basic-Class-Creation.md
This XML snippet demonstrates how to assign starting equipment to a class by adding the 'ClassEquipment' attribute with the corresponding equipment entry name in ClassDescriptions.lsx.
```xml
```
--------------------------------
### Example Oath Framework Config JSON
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Mod-Frameworks/oath-framework-usage.md
A concrete example of the Oath Framework configuration JSON, demonstrating specific values for subclass tags, event flags, and crimes that trigger oath reactions.
```json
{
"FileVersion": 1,
"Tags": [
{
"modGuids": [""],
"OathbreakerSubclassData": [
{
"SubclassTag": "PALADIN_ANCIENTS_7c89622b-4194-41df-b2ff-145a5056ee49",
"OathbreakerTag": "OATHBREAKER_ANCIENTS_d84a8a0b-b648-464c-9bd5-1ed9b965da2a",
"SubclassOathBrokenEventFlag": "GLO_PaladinOathbreaker_Event_AncientsBrokeOath_7cf0bd9c-f089-45a3-88fb-03087d3d8b95",
"CrimesToReact": ["Assault", "UseForbiddenItem", "Vandalise"]
}
]
}
]
}
```
--------------------------------
### Example of Replacer DB for Underwear Outfit
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Osiris/updating-epilogue-outfits.md
This example demonstrates the correct syntax for a 'Replacer' DB entry, specifying the game tag, the item to be applied, and the 'Underwear' equipment slot.
```Osiris
DB_MGNTN_EPIOutfitReplacers_ReplacementUnderwear_Fallback((TAG)REALLY_ELF_772b1dc6-14be-417f-afa3-c6cf364f45b4,(ITEMROOT)Underwear_Minsc_48a3ffbe-f14e-4cfe-b45e-ebadb3af0fd4,"Underwear");
```
--------------------------------
### Virtual Machine Setup for Toolkit
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Toolkit/Installing-the-Toolkit-on-Linux.md
Steps to set up a Windows 10 Tiny virtual machine for running the Baldur's Gate 3 Toolkit. This approach bypasses native Linux compatibility issues.
```text
- Share both the game and toolkit folders from the Linux host to the VM,
avoiding redundant downloads.
- Enable 3D graphics acceleration, which resolved the rendering issues.
- Achieve a "stable" environment where the toolkit runs...
```
--------------------------------
### Tag Framework Config - Example with BG3SX Disabled
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Mod-Integration/BG3SX/Whitelisting.md
An example of a race tag configuration where BG3SX support is explicitly disabled. This includes a custom reason for the decision and specifies the mod GUID.
```json
"Tags": [
{
"modGuids": ["bfc31d95-8fd5-4bdc-a92b-ec3bfce13f86"],
"Type": "Race",
"Tag": "Ghouls_Dunmer_f34cadf5-ccfb-4e56-9596-356619569108",
"ReallyTag": "REALLY_Ghouls_Dunmer_6a018dee-2f04-4bda-93c4-958422c3ed0a",
"BG3SX_Support": {
"Allowed": false,
"Reason": "The MPAA are watching me type",
"IncludeReally": true,
"RaceModGuid": "bfc31d95-8fd5-4bdc-a92b-ec3bfce13f86"
}
},
```
--------------------------------
### Instantiating a Class
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Classes/Basic-Class-Creation.html
Demonstrates how to create an instance (object) of the 'MyClass' and call its method. Ensure the class is defined before instantiation.
```csharp
MyClass myObject = new MyClass(10);
myObject.MyMethod();
```
--------------------------------
### Get Mod Information in SE API
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/test/temporary-se-docs.md
Retrieve module information using its GUID. Note that the `ExtIdeHelpers.GetMod` function returns a `Module` type with `Info` and `Dependencies` fields, which are not fully detailed in the current API.md.
```lua
ExtIdeHelpers: GetMod(modGuid: FixedString): Module
```
--------------------------------
### BG3 Mod Helper VSCode Extension Setup
Source: https://context7.com/bg3-community-library-team/bg3-community/llms.txt
Configure the BG3 Mod Helper extension in VSCode by setting paths for LSLib, Mod Destination, and Game Install Location. The Root Mod Path is auto-populated.
```text
Lslib Path : C:\...\ExportTool-v{version}\Packed
```
```text
Mod Destination Path : C:\Users\{user}\AppData\Local\Larian Studios\Baldur's Gate 3\Mods
```
```text
Game Install Location : C:\Program Files (x86)\Steam\steamapps\common\Baldur's Gate 3
```
--------------------------------
### Create BootstrapServer.lua
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Mod-Integration/BG3SX/Whitelisting.md
In the 'Lua' folder, create a 'BootstrapServer.lua' file. This file is executed when the mod loads and can be used for initial setup or debugging.
```text
project-folder/
│
├── Localization/
│
├── Mods/
│ └── YourModName
│ │
│ ├── ScriptExtender/
│ │ │
│ │ ├── Lua/
│ │ │ └── BootstrapServer.lua
│ │ │
│ │ └── config.json
│ │
│ └── meta.lsx
|
└── Public
```
--------------------------------
### Install Homebrew
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tools/LSLib-Macosx-Linux.html
Installs Homebrew, a package manager for MacOSX, which is required for subsequent installations.
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
--------------------------------
### Creating and Initializing Lua Tables
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/ScriptExtender/the_basics_of_lua.md
Demonstrates how to create empty Lua tables and tables pre-filled with initial values.
```lua
local myTable = {}
```
```lua
local myTable = {"Cheese", "Bread", "Wine"}
```
--------------------------------
### Install VMware Dependencies on Linux
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Toolkit/Installing-the-Toolkit-on-Linux.md
Installs necessary build tools before installing VMware Workstation Pro. Ensure you have the VMware bundle file downloaded.
```bash
sudo apt update
sudo apt install build-essential
sudo ./VMware-Workstation-Full-*.bundle
```
--------------------------------
### Whitelist Race with Example UUID
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Mod-Integration/BG3SX/Whitelisting.md
An example of whitelisting a race using a specific TagName and TagUUID.
```lua
if Mods.BG3SX then
Mods.BG3SX.Data.ModdedTags[ModuleUUID] = {}
local wList = Mods.BG3SX.Data.ModdedTags[ModuleUUID]
wList["MyCoolRaceTagName"] = {TAG = "413dcf04-586d-409f-aef1-1cf457711f5e", Allowed = true}
end
```
--------------------------------
### Usage Example: Remove Prefix from Display Name
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/ScriptExtender/changing-entity-name.md
Example of how to call the `RemovePrefixFromDisplayName` function with a specific entity and prefix.
```lua
RemovePrefixFromDisplayName(someEntity, "Stoneskin")
```
--------------------------------
### Example of meta.lsx Before Adding Dependencies
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/General/Basic/adding-mod-dependencies.md
This XML shows the structure of the 'Dependencies' node before any dependencies are added. It is typically an empty node.
```xml
...
```
--------------------------------
### Usage Example: Update Entity Display Name
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/ScriptExtender/changing-entity-name.md
Example of how to call the `UpdateEntityDisplayName` function with a specific entity and prefix.
```lua
UpdateEntityDisplayName(someEntity, "Stoneskin")
```
--------------------------------
### Instantiate a Class
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Classes/Basic-Class-Creation.md
Demonstrates how to create an instance (object) of a class and access its members.
```csharp
MyClass myObject = new MyClass(10);
myObject.MyMethod();
int value = myObject.MyProperty;
```
--------------------------------
### Install Wine Stable
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tools/LSLib-Macosx-Linux.html
Installs the stable version of Wine, a compatibility layer that allows running Windows applications on MacOSX.
```bash
brew install wine-stable
```
--------------------------------
### Create an ImGui Window
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/ScriptExtender/ImGui-and-You/Dear-ImGui.md
Use the Ext.IMGUI.NewWindow function to create a new ImGui window. Pass a string argument for the window's title.
```lua
Ext.IMGUI.NewWindow("My ImGui Window")
```
--------------------------------
### Example Voice Line Filename
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/new-voice-lines.md
An example of a correctly formatted voice line audio filename for a character named Jason.
```plaintext
v1323c4b692f74fda8bad6a96b8ddbc73_h580e6615c3364b05843d7575309ad942e568.wem
```
--------------------------------
### Unit Test Example
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/dribblespec.md
A unit test example using DribbleSpec's expect and toEqual matchers to compare table structures.
```lua
D.describe("Settings model", { tags = { "unit" } }, function()
D.test("toEqual enabled", function()
local expected = {
stable = { enabled = true },
}
local actual = {
stable = { enabled = true },
}
D.expect(actual).toEqual(expected)
end)
end)
```
--------------------------------
### Initialize Compatibility Framework
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Mod-Frameworks/compatibility-framework.md
Include this line in your BootstrapClient.lua to load the Compatibility Framework initialization script. Ensure your mod loads before the Compatibility Framework.
```lua
Ext.Require("InitCompatabilityFramework.lua")
```
--------------------------------
### Databases - Get
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/test/SE_API.md
Read data from Osiris databases using the `Get` method. Parameters filter rows based on column values.
```APIDOC
## Databases - Get
Databases can be read using the `Get` method. The method checks its parameters against the database and only returns rows that match the query.
The number of parameters passed to `Get` must be equivalent to the number of columns in the target database. Each parameter defines an (optional) filter on the corresponding column; if the parameter is `nil`, the column is not filtered (equivalent to passing `_` in Osiris). If the parameter is not `nil`, only rows with matching values will be returned.
### Example
```lua
-- Fetch all rows from DB_GiveTemplateFromNpcToPlayerDialogEvent
local rows = Osi.DB_GiveTemplateFromNpcToPlayerDialogEvent:Get(nil, nil, nil)
-- Fetch rows where the first column is CON_Drink_Cup_A_Tea_080d0e93-12e0-481f-9a71-f0e84ac4d5a9
local rows = Osi.DB_GiveTemplateFromNpcToPlayerDialogEvent:Get("CON_Drink_Cup_A_Tea_080d0e93-12e0-481f-9a71-f0e84ac4d5a9", nil, nil)
```
```
--------------------------------
### Keybinding_v2 Format with Options
Source: https://github.com/bg3-community-library-team/bg3-community/blob/main/Tutorials/Mod-Frameworks/mod-configuration-menu.md
Demonstrates the modern `keybinding_v2` format for defining a keybinding, including optional settings for behavior customization.
```json
{
"Id": "key_teleport_party_to_you",
"Name": "Teleport party to you shortcut",
"Type": "keybinding_v2",
"Default": {
"Keyboard": {
"Key": "T",
"ModifierKeys": ["LShift"]
}
},
// Options are optional; default values are shown
"Options": {
"ShouldTriggerOnKeyDown": true,
"ShouldTriggerOnKeyUp": false,
"ShouldTriggerOnRepeat": false,
"IsDeveloperOnly": false,
"BlockIfLevelNotStarted": false
}
}
```