### 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 } } ```