BG3 Modding Community Wiki

https://wiki.bg3.community
Admin
The BG3 Modding Community Wiki is a collaborative platform providing tutorials, resources, and...
Tokens:177,346
Snippets:2,139
Trust Score:5.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Inspiration Framework Configuration (Example)

Source: https://wiki.bg3.community/Tutorials/Mod-Frameworks/using-inspiration-framework

An example of the Inspiration Framework configuration file, showing a specific background and one of its goals registered.

```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"
        }
      ]
    }
  ]
}
```

--------------------------------

### Example: Tutorial Chest with Modded and Vanilla Items

Source: https://wiki.bg3.community/Tutorials/General/Shipping-Items-to-Users

This example demonstrates how to include both a modded item (Black Dye) and vanilla items (Supply Packs) in 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
```

--------------------------------

### Example Tag Framework Configuration

Source: https://wiki.bg3.community/Tutorials/Mod-Frameworks/using-tag-framework

An example JSON configuration file demonstrating the registration of custom race and deity tags, including exclusion and meta tags.

```json
{
  "FileVersion": 1,
  "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",
      "TagsToExclude": ["Baldurian"],
      "RaceMetaTags": ["Planar"]
    },
    {
      "Type": "Deity",
      "Tag": "Tyr",
      "DeityCleric": "TyrCleric",
      "DeityPaladin": "PALADIN_TYR_b8aec881-85fe-4e6e-8a28-7052ecd88899",
      "DeityAlignment": "Good"
    }
  ]
}
```

--------------------------------

### Example Tag Framework Race Configuration with BG3SX Support

Source: https://wiki.bg3.community/Tutorials/Mod-Integration/BG3SX/Whitelisting

An example of a `TagFrameworkConfig.json` entry for a race, demonstrating how to configure BG3SX support with specific values.

```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"
      }
  },

```

--------------------------------

### Example: Vendor Inventories for Arron and Dammon

Source: https://wiki.bg3.community/Tutorials/General/Shipping-Items-to-Users

This example shows how to add a modded Black Dye to Arron's inventory and Supply Packs to Dammon's inventory.

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

--------------------------------

### Complete Goal API Call (Example)

Source: https://wiki.bg3.community/Tutorials/Mod-Frameworks/using-inspiration-framework

An example of calling the 'CompleteGoal' function 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",
    }
  }
}
```

--------------------------------

### Example _merged.lsf.lsx File Structure

Source: https://wiki.bg3.community/Tutorials/Visual/Creating-A-Hair-Mod/File-Setup

This is an example of the _merged.lsf.lsx file, which tells the game where to locate your mesh and other required information. It's automatically converted to .lsf format by the multitool.

```xml
<region id="VisualBank">
       <node id="VisualBank">
           <children>
               <node id="Resource">
                   <attribute id="AttachBone" type="FixedString" value="" />
                   <attribute id="AttachmentSkeletonResource" type="FixedString" value="" />
                   <attribute id="BlueprintInstanceResourceID" type="FixedString" value="" />
                   <attribute id="BoundsMax" type="fvec3" value="0.1584038 1.846514 0.167948" />
                   <attribute id="BoundsMin" type="fvec3" value="-0.1540881 1.345605 -0.09591679" />
                   <attribute id="ClothColliderResourceID" type="FixedString" value="" />
                   <attribute id="HairPresetResourceId" type="FixedString" value="" />
                   <attribute id="HairType" type="uint8" value="0" />
                   <attribute id="ID" type="FixedString" value="955faf79-1707-4ea9-87f4-39a5fba49120" />
                   <attribute id="MaterialType" type="uint8" value="0" />
                   <attribute id="Name" type="LSString" value="AT_Hair01" />
                   <attribute id="NeedsSkeletonRemap" type="bool" value="True" />
                   <attribute id="RemapperSlotId" type="FixedString" value="" />
                   <attribute id="ScalpMaterialId" type="FixedString" value="55534266-4ce2-39d1-d2dd-04a8ec90e841" />
                   <attribute id="SkeletonResource" type="FixedString" value="78d8b5f0-726c-232f-a357-3d05c4b3b859" />
                   <attribute id="SkeletonSlot" type="FixedString" value="" />
                   <attribute id="Slot" type="FixedString" value="Hair" />
                   <attribute id="SoftbodyResourceID" type="FixedString" value="" />
                   <attribute id="SourceFile" type="LSString" value="Generated/Public/Autosnapping_Template/[PAK]_Autosnapping_Template/AT_Test.GR2" />
                   <attribute id="SupportsVertexColorMask" type="bool" value="False" />
                   <attribute id="Template" type="FixedString" value="Generated/Public/Autosnapping_Template/[PAK]_Autosnapping_Template/AT_Test.Dummy_Root.0" />
                   <attribute id="_OriginalFileVersion_" type="int64" value="144537400540921856" />
                   <children>
                       <node id="AnimationWaterfall">
                           <attribute id="Object" type="FixedString" value="" />
                       </node>
                       <node id="Base">
                           <children>
                               <node id="Tags">
                                   <attribute id="Object" type="FixedString" value="Hair" />
                               </node>
                           </children>
                       </node>
                       <node id="ClothProxyMapping" />
                       <node id="Objects">
                           <attribute id="LOD" type="uint8" value="0" />
                           <attribute id="MaterialID" type="FixedString" value="89b063ff-7bf3-44a8-7e7d-41b29d0dd469" />
                           <attribute id="ObjectID" type="FixedString" value="AT_Test.AT_Test_Mesh.0" />
                       </node>
```

--------------------------------

### Define Starting Equipment for Quickster Class

Source: https://wiki.bg3.community/Tutorials/Classes/Basic-Class-Creation

This snippet defines the starting equipment for the custom Quickster class in Equipment.txt. It includes daggers, a hand crossbow, healing potions, armor, and utility items.

```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"

```

--------------------------------

### BootstrapServer.lua Example

Source: https://wiki.bg3.community/Tutorials/Mod-Frameworks/oath-framework-usage

This script requires essential Lua files for your mod, including Globals, Actions, and Listeners, ensuring they are loaded in the correct order.

```lua
Ext.Require("Globals.lua")
Ext.Require("Actions/_init.lua")
Ext.Require("Listeners/_init.lua")
```

--------------------------------

### Install BG3-SE-Snippets Extension via Command

Source: https://wiki.bg3.community/Tutorials/ScriptExtender/GettingStarted

Use this command in VSCode's command palette to manually install the BG3-SE-Snippets extension if it's not found through the Extensions view. Press Ctrl+P in VSCode, paste the command, and press Enter.

```bash
ext install FallenStar.bg3-se-snippets
```

--------------------------------

### Actions/_init.lua Example

Source: https://wiki.bg3.community/Tutorials/Mod-Frameworks/oath-framework-usage

Initializes the 'Actions' table and requires specific action files, organizing your mod's event handling logic.

```lua
-- We want Actions to be in its own category/table, so it's easier to reference things
Actions = {}

Ext.Require("Actions/MercyToHag.lua")
```

--------------------------------

### Define a Basic Class

Source: https://wiki.bg3.community/Tutorials/Classes/Basic-Class-Creation

Demonstrates the syntax for creating a simple class with a constructor and a method. Use this as a starting point for defining your own custom objects.

```csharp
public class MyClass
{
    public int MyProperty { get; set; }

    public MyClass(int value)
    {
        MyProperty = value;
    }

    public void MyMethod()
    {
        Console.WriteLine($"Property value: {MyProperty}");
    }
}
```

--------------------------------

### Example KAVT Customization File Structure

Source: https://wiki.bg3.community/Tutorials/Mod-Use/KAVT-User-Manual

This is an example of how a KAVT customization file for a specific race might appear after opening it in a text editor. It shows the structure for editing Subrace and Body Type combinations.

```xml
<CharacterVisuals>
  <SubRace>
    <Body Type="0">
      <!— KAVT CUSTOMIZATION —>
      <Attribute id="1" value="0" />
      <Attribute id="2" value="0" />
      <!— KAVT CUSTOMIZATION END —>
    </Body>
    <Body Type="1">
      <!— KAVT CUSTOMIZATION —>
      <Attribute id="1" value="0" />
      <Attribute id="2" value="0" />
      <!— KAVT CUSTOMIZATION END —>
    </Body>
  </SubRace>
</CharacterVisuals>
```

--------------------------------

### Define Starting Equipment for Bard Class

Source: https://wiki.bg3.community/Tutorials/Classes/Basic-Class-Creation

This snippet defines the starting equipment for the Bard class in Equipment.txt. It includes various weapons, healing potions, scrolls, armor, and utility items.

```txt
new equipment "EQP_CC_Bard"
add initialweaponset "Melee"
add equipmentgroup
add equipment entry "WPN_Rapier"
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_Bard"
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 Oath Framework Configuration JSON with Specific Values

Source: https://wiki.bg3.community/Tutorials/Mod-Frameworks/oath-framework-usage

An example of the Oath Framework configuration JSON with specific values for subclass and oathbreaker tags, and event flags. Includes optional crime 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"]
        }
      ]
    }
  ]
}
```

--------------------------------

### Animation and Base Node Setup

Source: https://wiki.bg3.community/Tutorials/Visual/Creating-A-Hair-Mod/File-Setup

This section includes nodes for animation and base tags. The 'Tags' node should have 'Hair' assigned as its object.

```xml
<node id="AnimationWaterfall"> <attribute id="Object" type="FixedString" value="" /> </node> <node id="Base"> <children> <node id="Tags"> <attribute id="Object" type="FixedString" value="Hair" /> </node> </children> </node>
```

--------------------------------

### Table-based Arguments Example

Source: https://wiki.bg3.community/Tutorials/Mod-Frameworks/mod-configuration-menu

Starting with MCM version 1.38+, the API supports table-based arguments as a better alternative to positional arguments. This pattern makes function calls more readable and self-documenting.

```APIDOC
## MCM.EventButton.ShowFeedback

### Description
Shows feedback for an event button.

### Method
`MCM.EventButton.ShowFeedback(options)`

### Parameters
- **options** (table) - Configuration options for the feedback.
  - **buttonId** (string) - The ID of the button.
  - **message** (string) - The feedback message to display.
  - **feedbackType** (string) - The type of feedback (e.g., 'success', 'error'). Can also use `MCM.EventButton.FeedbackTypes` constants.
  - **modUUID** (string, optional) - The UUID of the mod. Defaults to the current mod's UUID.
  - **durationInMs** (number, optional) - The duration in milliseconds to display the feedback. Defaults to 5000.

### Request Example
```lua
MCM.EventButton.ShowFeedback({
    buttonId = "my_button",
    message = "Action completed successfully!",
    feedbackType = "success",       -- or use MCM.EventButton.FeedbackTypes.SUCCESS
    modUUID = "optional-mod-uuid",  -- Optional, will default to your mod UUID
    durationInMs = 5000             -- Optional, already defaults to 5000
})
```
```

--------------------------------

### Example: Registering and Adding Spawn Entries

Source: https://wiki.bg3.community/Tutorials/Mod-Integration/More-Firewine-Kobolds

Demonstrates registering a new spawn template for a stealth kobold and then adding it as an entry to the 'WLD' region with a specific weight. Also shows adding an inline entry to the 'SCL' region and changing the weight of an existing entry in 'WLD_Main_A'.

```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" }})

-- Add a new entry to a region using a spawn template
Mods.MoreFirewineKobolds.API.AddRegionEntry("WLD", {
  SpawnTemplate = "StealthRangerKobold",
  Weight = 25
})

-- 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
})

-- Change the weight of an existing entry
Mods.MoreFirewineKobolds.API.SetEntryWeight("WLD_Main_A", "DrunkKobold", 40)
```

--------------------------------

### Usage Example for RemovePrefixFromDisplayName

Source: https://wiki.bg3.community/Tutorials/ScriptExtender/changing-entity-name

Example of how to call the RemovePrefixFromDisplayName function with a specific entity and prefix.

```lua
RemovePrefixFromDisplayName(someEntity, "Stoneskin")
```

--------------------------------

### Usage Example for UpdateEntityDisplayName

Source: https://wiki.bg3.community/Tutorials/ScriptExtender/changing-entity-name

Example of how to call the UpdateEntityDisplayName function with a specific entity and prefix.

```lua
UpdateEntityDisplayName(someEntity, "Stoneskin")
```

--------------------------------

### Instantiate and Use a Class

Source: https://wiki.bg3.community/Tutorials/Classes/Basic-Class-Creation

Shows how to create an instance of a class and call its methods. This is essential for working with objects in your programs.

```csharp
var myObject = new MyClass(10);
myObject.MyMethod();
```

--------------------------------

### Composite Template Example

Source: https://wiki.bg3.community/Tutorials/Mod-Integration/More-Firewine-Kobolds

This example demonstrates how to define a composite template that spawns multiple creatures together. It references existing atomic templates.

```json
"SCL_KoboldEncounter": {
  "Members": [
    { "Template": "TwoNormalKobolds" },
    { "Template": "DrunkKobold" }
  ]
}
```

--------------------------------

### Create Companion Instances

Source: https://wiki.bg3.community/Tutorials/ScriptExtender/the_basics_of_lua

Demonstrates how to create new Companion objects using the 'new' constructor. Each instance is initialized with specific attributes.

```lua
-- Main.lua

-- Creating a companion named Astarion
local astarion = Companion:new("Astarion", 100, "Rogue")

-- Creating another companion named Gale
local gale = Companion:new("Gale", 120, "Wizard")
```

--------------------------------

### Get Region with Script Extender

Source: https://wiki.bg3.community/Tutorials/Items/Add-and-position-items-in-world

Use this command in the Script Extender console to get the current region's name, which is needed for data files.

```lua
_P(Osi.GetRegion(GetHostCharacter()))
```

--------------------------------

### Define Keybinding (keybinding_v2 Format)

Source: https://wiki.bg3.community/Tutorials/Mod-Frameworks/mod-configuration-menu

This example shows the recommended `keybinding_v2` format for defining a keybinding in a mod's blueprint file. It includes default settings and optional configurations for trigger behavior.

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

--------------------------------

### Inspiration Framework Configuration (Sample)

Source: https://wiki.bg3.community/Tutorials/Mod-Frameworks/using-inspiration-framework

This JSON file configures the Inspiration Framework, registering custom backgrounds and their associated goals. The 'Id' for backgrounds and goals should be unique UUIDs.

```json
{
  "FileVersion": 1,
  "Backgrounds": [
    {
      "Name": "Name of Background",
      "Id": "UUID of Background Entry",
      "Goals": [
        {
          "Name": "Identifier for your Background Goal - Convention: Act#_BackgroundName_ShortGoalDescriptor or GLO_BackgroundName_ShortGoalDescriptor",
          "Id": "UUID of BackgroundGoals Entry",
          "Global": "Optional. Defaults to Global if not supplied. Should be either Global or GlobalAvatar"
        }
      ]
    }
  ]
}
```

--------------------------------

### Define Starting Equipment for Barbarian Class

Source: https://wiki.bg3.community/Tutorials/Classes/Basic-Class-Creation

This snippet defines the starting equipment for the Barbarian class in Equipment.txt. It includes melee weapons, potions, scrolls, armor, and utility items.

```txt
new equipment "EQP_CC_Barbarian"
add initialweaponset "Melee"
add equipmentgroup
add equipment entry "WPN_Greataxe"
add equipmentgroup
add equipment entry "OBJ_Potion_Healing"
add equipmentgroup
add equipment entry "OBJ_Potion_Healing"
add equipmentgroup
add equipment entry "OBJ_Scroll_Revivify"
add equipmentgroup
add equipment entry "ARM_Shoes_Barbarian"
add equipmentgroup
add equipment entry "ARM_Barbarian"
add equipmentgroup
add equipment entry "WPN_Handaxe"
add equipmentgroup
add equipment entry "WPN_Handaxe"
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"

```

--------------------------------

### Print 'Hello World' in SE Console

Source: https://wiki.bg3.community/Tutorials/ScriptExtender/GettingStarted

Use this command to verify the Script Extender console is working and to print simple text messages.

```lua
_P("Hello World")
```

--------------------------------

### Subclass Progression with Boost Example

Source: https://wiki.bg3.community/Tutorials/Classes/Basic-Class-Creation

This XML snippet shows an example of adding a 'Boost' attribute to a subclass progression. In this case, it grants the subclass 'ActionResource(SpellSlot,2,1)', providing 2 spell slots.

```xml
<attribute id="Boosts" type="LSString" value="ActionResource(SpellSlot,2,1)"/>
```

--------------------------------

### Link Equipment to Class Description

Source: https://wiki.bg3.community/Tutorials/Classes/Basic-Class-Creation

This XML snippet shows how to assign starting equipment to a class by setting the 'ClassEquipment' attribute in the ClassDescription node. The value should match the equipment entry name defined in Equipment.txt.

```xml
...
<node id="ClassDescription">
  <attribute id="BaseHp" type="int32" value="6"/>
  <attribute id="CharacterCreationPose" type="guid" value="0f07ec6e-4ef0-434e-9a51-1353260ccff8"/>
  <attribute id="ClassEquipment" type="FixedString" value="EQP_CC_Quickster"/>
  <attribute id="Description" type="TranslatedString" handle="hc25377a0g8e44g4645g90c5gee05d6c5e31b" version="1"/>
  <attribute id="DisplayName" type="TranslatedString" handle="heb6d4970g5238g4bb8ga932g9dd4357d61ed" version="1"/>
  <attribute id="HpPerLevel" type="int32" value="4"/>
  <attribute id="LearningStrategy" type="uint8" value="1"/>
  <attribute id="Name" type="FixedString" value="Quickster"/>
  <attribute id="PrimaryAbility" type="uint8" value="6"/>
  <attribute id="ProgressionTableUUID" type="guid" value="b283c957-2267-484a-a6c0-f98479c55e53"/>
  <attribute id="SoundClassType" type="FixedString" value="Paladin"/>
  <attribute id="SpellCastingAbility" type="uint8" value="2"/>
  <attribute id="UUID" type="guid" value="e7b0f304-da32-410e-9e58-6efea9272673"/>
  <children>
    <node id="Tags">
      <attribute id="Object" type="guid" value="35add446-b710-4ad1-8dbc-36f99aecc6d5"/>
    </node>
  </children>
</node>
...

```

--------------------------------

### Initialize a New Git Repository

Source: https://wiki.bg3.community/Tutorials/General/modders-guide-to-git/working-with-repositories

Use this command in your project's root directory to start tracking changes with Git. This creates a hidden .git folder to store repository data.

```bash
git init
```

--------------------------------

### Initialize Compatibility Framework API

Source: https://wiki.bg3.community/Tutorials/Mod-Frameworks/compatibility-framework

Include this script in your mod to register custom subclasses with the Compatibility Framework. Ensure your mod loads before the framework itself.

```lua
modGuid = "your-mods-uuid-in-metalsx"
subClassGuid = "your-subclasses-class-description-uuid"

if Ext.Mod.IsModLoaded("67fbbd53-7c7d-4cfa-9409-6d737b4d92a9") then
  local subClasses = {
    AuthorSubclass = {
      modGuid = modGuid,
      subClassGuid = subClassGuid,
      class = "lowercase parent class name or uuid of the progression where you get the subclass choice",
      subClassName = "English-localized name for your class (Optional)"
    }
  }

  local function OnStatsLoaded()
    Mods.SubclassCompatibilityFramework.Api.InsertSubClasses(subClasses)
  end

  Ext.Events.StatsLoaded:Subscribe(OnStatsLoaded)
end
```

--------------------------------

### StatFunctorsContext Example

Source: https://wiki.bg3.community/Tutorials/Classes/Basic-Class-Creation

Defines triggers for passive abilities. Multiple triggers are separated by semicolons.

```string
OnCast;OnStatusRemoved;OnStatusApplied
```

--------------------------------

### Localization Handle Example in Blueprint

Source: https://wiki.bg3.community/Tutorials/Mod-Frameworks/mod-configuration-menu

Demonstrates how to use localization handles for UI elements like tab names within the MCM blueprint JSON. Ensure handles are listed in a .loca file for localization to work.

```json
{
    "TabId": "myTab",
    "TabName": "My tab default display name",
    "Handles": {
        "NameHandle": "h3b019e17g75fcg48ccg8063g4de5bfcc7792"
    }
}
```

--------------------------------

### Core API Functions

Source: https://wiki.bg3.community/Tutorials/Mod-Frameworks/mod-configuration-menu

Functions for getting and setting general mod configuration values.

```APIDOC
## MCM.Get

### Description
Gets the value of a specific setting.

### Method
MCM.Get(settingId, modUUID?)

### Parameters
- **settingId** (string) - Required - The unique identifier for the setting.
- **modUUID** (string) - Optional - The UUID of the mod the setting belongs to.
```

```APIDOC
## MCM.Set

### Description
Sets the value of a specific setting.

### Method
MCM.Set(settingId, value, modUUID?, shouldEmitEvent?)

### Parameters
- **settingId** (string) - Required - The unique identifier for the setting.
- **value** (any) - Required - The new value to set for the setting.
- **modUUID** (string) - Optional - The UUID of the mod the setting belongs to.
- **shouldEmitEvent** (boolean) - Optional - Whether to emit an event after setting the value.
```

--------------------------------

### Define Weapon Entry - Weapon.txt

Source: https://wiki.bg3.community/Tutorials/Classes/Basic-Class-Creation

Use this format to define a new weapon entry in Weapon.txt. Specify its type, base template, damage, and equip bonuses.

```txt
new entry "WPN_Dagger"
type "Weapon"
using "_BaseWeapon"
data "RootTemplate" "569b0f3d-abcd-4b01-aaf0-979091288163"
data "Damage Type" "Piercing"
data "Damage" "1d4"
data "ValueScale" "0.5"
data "Weight" "0.45"
data "BoostsOnEquipMainHand" "UnlockSpell(Target_PiercingThrust)"
data "Weapon Group" "SimpleMeleeWeapon"
data "Weapon Properties" "Finesse;Light;Thrown;Melee;Dippable"
data "Proficiency Group" "Daggers;SimpleWeapons"
```

```txt
new entry "WPN_HandCrossbow"
type "Weapon"
using "_BaseWeapon"
data "RootTemplate" "a5d843ab-c3af-4e60-a925-bb2e15828938"
data "Damage Type" "Piercing"
data "Damage" "1d6"
data "Damage Range" "3000"
data "WeaponRange" "1500"
data "ValueLevel" "3"
data "Weight" "0.9"
data "Slot" "Ranged Main Weapon"
data "Projectile" "ff93ba9c-124c-454e-ac8c-436c136bcef2"
data "BoostsOnEquipMainHand" "UnlockSpell(Projectile_PiercingShot);UnlockSpell(Projectile_MobileShooting)"
data "Weapon Group" "MartialRangedWeapon"
data "Weapon Properties" "Ammunition;Loading;Light;Dippable"
data "Proficiency Group" "HandCrossbows;MartialWeapons"
```

--------------------------------

### Condition Check Example

Source: https://wiki.bg3.community/Tutorials/Classes/Basic-Class-Creation

Checks if a passive ability should run by evaluating multiple conditions. Uses logical AND and NOT operators.

```string
(context.HasContextFlag(StatsFunctorContext.OnCast) and ExtraAttackSpellCheck() and HasUseCosts('ActionPoint', true) and not ...
```

--------------------------------

### Example Usage of Public API

Source: https://wiki.bg3.community/Tutorials/Mod-Integration/More-Firewine-Kobolds

Demonstrates how to use the More Firewine Kobolds public API functions to register spawn templates, add region entries, and modify weights.

```APIDOC
## Example Usage

-- 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" }})

-- Add a new entry to a region using a spawn template
Mods.MoreFirewineKobolds.API.AddRegionEntry("WLD", {
  SpawnTemplate = "StealthRangerKobold",
  Weight = 25
})

-- 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
})

-- Change the weight of an existing entry
Mods.MoreFirewineKobolds.API.SetEntryWeight("WLD_Main_A", "DrunkKobold", 40)
```

--------------------------------

### XML for Localization File

Source: https://wiki.bg3.community/Tutorials/Visual/Creating-A-Hair-Mod/File-Setup

Example structure for a .loca.xml file used for localizing custom mod content, such as hair names.

```xml
<?xml version="1.0" encoding="UTF-8">
<?xml-stylesheet type="text/xsl" href="./../../../../table_layout.xsl"?>
<table>
	<thead>
		<tr>
			<th>GUID</th>
			<th>Text</th>
			<th>Comment</th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td>{2B2A3A7A-1A2B-3C4D-5E6F-7A8B9C0D1E2F}</td>
			<td>My Hair Name</td>
			<td></td>
		</tr>
	</tbody>
</table>
```

--------------------------------

### ClassDescription.lsx Example

Source: https://wiki.bg3.community/Tutorials/Classes/Basic-Class-Creation

This XML structure defines a new character class, 'Quickster', within the game's data. It includes essential attributes for base stats, abilities, and identifiers.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<save>
    <version major="4" minor="3" revision="0" build="333"/>
    <region id="ClassDescriptions">
        <node id="root">
            <children>
                <node id="ClassDescription">
                    <attribute id="BaseHp" type="int32" value="6"/>
                    <attribute id="CharacterCreationPose" type="guid" value="0f07ec6e-4ef0-434e-9a51-1353260ccff8"/>
                    <attribute id="Description" type="TranslatedString" handle="hc25377a0g8e44g4645g90c5gee05d6c5e31b" version="1"/>
                    <attribute id="DisplayName" type="TranslatedString" handle="heb6d4970g5238g4bb8ga932g9dd4357d61ed" version="1"/>
                    <attribute id="HpPerLevel" type="int32" value="4"/>
                    <attribute id="LearningStrategy" type="uint8" value="1"/>
                    <attribute id="Name" type="FixedString" value="Quickster"/>
                    <attribute id="PrimaryAbility" type="uint8" value="6"/>
                    <attribute id="ProgressionTableUUID" type="guid" value="b283c957-2267-484a-a6c0-f98479c55e53"/>
                    <attribute id="SoundClassType" type="FixedString" value="Paladin"/>
                    <attribute id="SpellCastingAbility" type="uint8" value="2"/>
                    <attribute id="UUID" type="guid" value="e7b0f304-da32-410e-9e58-6efea9272673"/>
                </node>
            </children>
        </node>
    </region>
</save>
```

--------------------------------

### Add Gold to the Host Character

Source: https://wiki.bg3.community/Tutorials/ScriptExtender/GettingStarted

Example of using `Osi.AddGold` by passing the result of `Osi.GetHostCharacter()` as the `inventoryHolder` and a numerical value for the `amount`.

```lua
Osi.AddGold(Osi.GetHostCharacter(), 999)
```
Tokens:
Raw