UI

UI modding is done through XAML editing, and all mods have access to the same functionality and data as the existing BG3 UIs.

External Links

• All possible information about XAML coding and the Microsoft WPF framework that our UI is based on: Getting Started - WPF .NET Framework
• All Noesis-specific information: noesisGUI Documentation
  • Noesis is the third-party framework we use. It replicates the Microsoft WPF framework. We use version 3.1.6 of Noesis.

We will link to the relevant sections of the different frameworks, so don’t worry about reading a thousand pages before starting!

Setup

You’ll first have to get your mod created, as explained in Getting Started: Creating a New Mod. Once that is done, you can start adding the UI-specific requirements to the mod.

Setting Up the Folder Structure

Inside your mod project’s folder (...\steamapps\common\Baldurs Gate 3\Data\<YourMod>\), you’ll need to set up the file and folder structure according to the image below:

The required folder structure inside your mod folder.

As for what these folders and files do:

Folder/File	Notes
Assets	A folder for organising all your assets (images and the like). All assets should be in the .dds format and, ideally, defined inside your Resources. There's more information on the DDS conversion settings later in this guide.
Library	A folder containing your resource libraries (templates and styles that use your Resources data). You can have as many resource libraries in here as you like. However, the following pair is required. These two can contain templates and styles on their own, as well as a merged dictionary with all the dictionary XAMLs inside this folder. Lib_Controller.xaml: The dictionary that is loaded in controller mode. Lib_Keyboard.xaml: The dictionary that is loaded in keyboard and mouse mode.
Pages	A folder to organise all your actual UIs.
Resources	A folder containing the required Resources.xaml as well as all your extra resource .xaml files, like registered images, brushes, fonts, colours, etc. Resources.xaml: Contains all the registered asset resources as well as single line resource declarations.
StateMachines	A folder that should contain only the two following files. They are the link to your UI; this is where the UI flow is determined and where your pages are used. Controller.xaml: Your modified UIs in controller mode. Keyboard.xaml: Your modified UIs in keyboard and mouse mode.
metadata.lsf	A metadata file that is required to be able to preload some file info from the .dds assets inside the Assets folder.

ⓘ Resources are loaded before the libraries, since their keys are used inside the libraries. All mod resources and libraries are loaded before the mod StateMachines are applied.

Assets

Although the used images inside your .xaml files have the .png extension, in the background, that extension gets swapped to .dds. The UI assets used need to be a specific .dds format.

DDS Conversion Settings

if image.mode == "RGBA":
if sRGBBool:
target_mode = "BC7_UNORM_SRGB"
else:
target_mode = "BC7_UNORM"
if image.mode == "RGB":
target_mode = "BC1_UNORM"

Resources

Resources are a collection of ResourceDictionaries that can be merged into ResourceDictionaryContained inside Resources.xaml. If you don't see the need to organise your resources into multiple files, all of them can be placed directly inside Resources.xaml.

Resources are all:

• fonts
• colours
• brushes
• imagesources
• predefined variable types

The following is an example of a Resources.xaml file.

<ResourceDictionary xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
                    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
                    xmlns:sys="clr-namespace:System;assembly=mscorlib">
    
    <ResourceDictionary.MergedDictionaries>
      <ResourceDictionary Source="/Core;component/Resources/OtherResourceFile.xaml" />
    </ResourceDictionary.MergedDictionaries>
    
    <BitmapImage x:Key="generalWarningIcon" UriSource="/ModBrowser;component/Assets/ico_warning_general.png"/>
    <BitmapImage x:Key="modioIcon" UriSource="/ModBrowser;component/Assets/ico_modio.png"/>
    <BitmapImage x:Key="splashScreenPanelDivider" UriSource="/ModBrowser;component/Assets/mods_introPane_panelDivider.png"/>
    <BitmapImage x:Key="splashScreenBg" UriSource="/ModBrowser;component/Assets/mods_introPane_panelBG.png"/>
    
    <FontFamily x:Key="DefaultFont" >pack://application:,,,/Core;component/Assets/Fonts/Alegreya/#Alegreya</FontFamily>
    <FontFamily x:Key="SpecialFont" >pack://application:,,,/Core;component/Assets/Fonts/AlegreyaSans/#Alegreya Sans</FontFamily>

    <Color x:Key="accent00Color">#584537</Color>
    <Color x:Key="accent25Color">#7d604a</Color>
    <Color x:Key="baseColor">#af8768</Color>
    <Color x:Key="accent75Color">#cbac95</Color>
    <Color x:Key="accent100Color">#E6DBC2</Color>
    <Color x:Key="disabledPadTxtColor">#7C6354</Color>
    
    <SolidColorBrush x:Key="LS_accent100TxtColor" Color="{StaticResource accent100Color}"/>
    <SolidColorBrush x:Key="LS_accent75TxtColor" Color="{StaticResource accent75Color}"/>
    <SolidColorBrush x:Key="LS_baseTxtColor" Color="{StaticResource baseColor}"/>
    <SolidColorBrush x:Key="LS_accent25TxtColor" Color="{StaticResource accent25Color}"/>
    
    <System:Double x:Key="InvSlotSize">116</System:Double>
    <System:Double x:Key="FilterSlotSize">84</System:Double>
    
    <Thickness x:Key="extraSectionPadding">0,0,0,0</Thickness>
    <Thickness x:Key="TextTopBottomMargin">0,12</Thickness>
    
</ResourceDictionary>

Library

The Library contains a collection of ResourceDictionaries that can be merged into the Lib_<>.xaml file specific to your input method:

• Keyboard and mouse mode will load Lib_Keyboard.xaml
• Controller mode will load Lib_Controller.xaml

You can organise your templates and styles directly inside these libraries, or you can decide to organise them in extra files and merge those inside the required keyboard and controller libraries.

The following is an example of Lib_Keyboard.xaml:

<ResourceDictionary xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
                    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
                    xmlns:sys="clr-namespace:System;assembly=mscorlib">
    
    <ResourceDictionary.MergedDictionaries>
      <ResourceDictionary Source="/MyMod;component/Library/Buttons.xaml" />
      <ResourceDictionary Source="/MyMod;component/Library/Panels.xaml" />
    </ResourceDictionary.MergedDictionaries>
    
    <Style x:Key="StyleA" TargetType="ContentControl">
      ...
    </Style>
    
    <ControlTemplate x:Key="ListItem" TargetType="ListBoxItem">
      <Grid x:Name="Root">
        ...
      <Grid>
      <ControlTemplate.Triggers>
        ...
      </ControlTemplate.Triggers>
    <ControlTemplate>
    
</ResourceDictionary>

StateMachines

If your mod is only for keyboard and mouse or controller, this folder will only contain one file. If the mod applies to both UI modes, it will contain two.

ⓘ Without these files, the Pages you add inside your mod will not be accessible because the framework will not recognise a change to the UI flow.

Other Notes

When you want to mod the UI, whether it’s adding a panel, overriding a panel, or overhauling the flow, your mod will link into the UI StateMachine. The StateMachine is the flow of the UI – it has UI states defined and linked to each other.

ⓘ When loading mods, the order matters. A mod can be added that defines new moddable root states for other mods to hook into. A mod can overhaul the entire UI, but you want one of those to be overridden by a next mod. While loading, the StateMachine is built mod per mod, and the final result is the sum of all the mods in sequence.

UI Guide Links

See also:

• Extending UI