Building a Race Mod

Race Mods

One of the easiest ways to get into modding is create a custom race. Whether you have a cool homebrew concept, or there's an official race that Larian didn't add, there's a lot of room to play around in. This guide will walk you through the process of building a custom race.

Table of Contents

1. Getting Started
2. File Layout
3. Race Entry
4. Character Creation
5. Localization
6. Root Templates
7. Racial Feats
8. Racial Progressions
9. Custom Icons

Getting Started

There's a lot that goes into creating a custom race, but overall it's one of the easier things to do. This guide will go with the assumption that you're building this with the Community Library in mind. If you want to create a race, but don't want to include any parts of it in the community library, this guide will still be applicable, but you may need to make some modifications. You'll also want to skip the rest of this step and head straight to File Layout.

Building a mod for Community Library involves adding the base components into the Community Library, and building a separate Implementation Mod. To get started, make sure you've followed the steps outlined in our How to Contribute and Setting up a Development Environment pages, and have pulled down your own copy of the Community Library.

What you need

1. VSCode, or other preferred text editor/IDE
2. Git
3. A local fork of Community Library
4. LSLib
5. Modder's Multitool

Now, before we start, let's just make sure we have the latest code.

1. Open Gitbash in your Community Library folder.
2. Input get checkout main to navigate to the main branch.
3. Input git fetch && git pull to make sure you have the latest version of the project
4. Finally, Input git checkout -b BRANCHNAME, substituting BRANCHNAME with a descriptive name of your branch.

File Layout

For our Implementation Mod, we'll need to set up a file structure, outside of our Community Library folder. Let's assume something like this, and add and remove as we go:

ModName/ModName/
        /Localization/English/ModName.xml
        /Mod/meta.lsx
        /Public/ModName/...

Of course, sub English with whichever language you want to release your mod in. For the sake of this tutorial, we'll assume English.

Race Entry

First thing's first, we need to work on our Races.lsx entry. Typically, this is something you'll want the Community Library to handle, as it's reusable and potentially useful for other modders. Community Library already has an existing Races.lsx file, located in CommunityLibrary/Public/CommunityLibrary/Races/Races.lsx, so that's where we'll start.

1. Open up Community Library in VSCode(or your IDE of choice).
2. Open up CommunityLibrary/Public/CommunityLibrary/Races/Races.lsx

Here, we can see there are already a few entries in here. We can use these as examples, but it's worth taking a look at some of the default files, especially if there are any races similar to what you want to include. If you haven't already, unpack the Shared and Gustav .pak files:

1. Open Modder's Multitool
2. Select "Unpack .pak Files
3. Tick "Gustav.pak" and "Shared.pak."
4. Select "Confirm," and wait for the process to complete.

Take a look at the Races.lsx files unpacked form Gustav and/or Shared.pak, and identify a similar race. This will be important later.

Now, let's look at our copy again. What's important to us are the nodes with an ID of "Race". Here's the entry for Shadar-Kai.

<node id="Race">
  <attribute id="Description" type="TranslatedString" handle="h9a4e44c9g72e0g43b6ga72bgd83fcb6b40d1" version="1"/>
  <attribute id="DisplayName" type="TranslatedString" handle="h6362370ag39d0g407fgaff0g3d98f3bb161e" version="1"/>
  <attribute id="DisplayTypeUUID" type="guid" value="899d275e-9893-490a-9cd5-be856794929f"/>
  <attribute id="Name" type="FixedString" value="CL_ShadarKai"/>
  <attribute id="ParentGuid" type="guid" value="6c038dcb-7eb5-431d-84f8-cecfaf1c0c5a"/>
  <attribute id="ProgressionTableUUID" type="guid" value="01735427-a4df-4ce4-8fb6-4b1b8c6c3771"/>
  <attribute id="RaceSoundSwitch" type="FixedString" value="Elf"/>
  <attribute id="UUID" type="guid" value="27844147-3e0f-4b2e-8377-8d015b8384df"/>
  <children>
    ...
  <children>
</node>

It's a lot to look at, I know. For now, ignore the <children> section. We have a few attributes:

• Description: The value here refers to a localization string that defines the race's description.
• DisplayName: The value here refers to a localization string that defines the race's name, as seen ingame.
• DisplayTypeUUID: This will often be identical to the later ParentGuid attribute. Just keep these the same.
• Name: This is the internal name of the Race - never seen ingame, but useful when referencing.
• ParentGuid: The Race this race inherits from. Base races will often inherit from the Humanoid race, while subraces may inherit from other races.
• ProgressionTableUUID: This references a specific progression table, defining spells, passives, and other key pieces. More on this later.
• RaceSoundSwitch: References the sound types made when switching characters.
• UUID: This is the Identifier of this race. It's how you'll reference the race when needed.

So what do we do with this? Let's start by copy/pasting it as a new Race node, and making our changes.

1. Using Modder's Multitool, tick "Handle", and generate a new UUID.
2. Copy the UUID(click on it's display), and paste it into Description's handle value.
3. Do the same for DisplayName.
4. Write an internal name, prefixed with CL_ to help ensure there aren't any collisions with other mods
5. Set the RaceSoundSwitch based on another similar race.
6. Untick "Handle" in Modder's Multitool, and generate a new UUID, pasting it into the UUID attribute's handle field.

Subraces

1. Find the race you want your race to be a subrace of
2. Copy its UUID handle
3. Paste it into your race's ParentGuid value.

We can work with the Progression Table once we get to Progressions, but this should do for now.

Character Creation

// TODO

Localization

// TODO

Root Templates

// TODO

Racial Feats

// TODO

Racial Progressions

// TODO

Custom Icons

Now that you've got everything set up, there's one thing that might be bothering you.

It exists, that's for sure. It might even be fine as is. But if you want something unique, something that draws the player's attention and really says "This is my custom race, right here," this section is for you.

I'm here to tell you that it's quite possible, with a bit of legwork. If you don't have an icon in mind yet, that's fine. Come back to this step when you've got something you want. This guide won't walk you through the artistic creation of the icon, although you'll want to make sure of a few things:

1. Make sure your desired icon is 196x196.\
2. Use the naming scheme Race_Subrace.fileextension (for example, Elf_ShadarKai.png)
3. Save a copy of your icon in .png format
4. Save another copy in .DDS format (all caps).

Forking BG3 ImprovedUI and Importing Icons

Now you're ready to plug it in. To do this, you'll need to create a fork of BG3 ImprovedUI.

1. Fork the Repository
2. Clone your forked repository to your PC and make a new branch: `git checkout -b "MyRaceName-icons" 3.open it up in VSCode.
3. Navigate to or create the directory ImprovedUI/Public/Game/GUI/Assets/CC/icons_races
4. Drop your race icons into the icons_races folder.

Editing the XAML

It's time to edit the .xaml files.

1. Navigate to ImprovedUI/Public/Game/GUI/Assets/Library folder
2. Open the file DataTemplates.xaml 3 Look for the DataTrigger elements referencing Racial icons. It will look something like this:

<DataTrigger Binding="{Binding Guid}" Value="a459ba68-a9ec-4c8e-b127-602615f5b4c0">
    <Setter Property="OpacityMask">
        <Setter.Value>
            <ImageBrush ImageSource="pack://application:,,,/GustavNoesisGUI;component/Assets/CC/icons_races/Elf_WoodElf.png"/>
        </Setter.Value>
    </Setter>
</DataTrigger>

4. If making a subrace, find the DataTrigger that is nearest to your subraces main race, otherwise go to the last of the Race-related DataTriggers.
5. Copy and Paste the DataTrigger and its child elements beneath the one you found.
6. Edit the component/Assets/CC/icons_races/filename.png to match your race icon's filename.
7. Save the file

Packaging and Testing

So we're ready to make a Pull Request and make this official, right? Not quite. First, let's test the icon - make sure it looks like how you want it.

1. Open LSLib's ConverterApp
2. Navigate to PAK/LSV Tools
3. Under "Create Package," set the Priority field to 21
4. Also make sure the version is V18 (Baldur's Gate 3 Release)
5. Enter your Source Path and expected Package Path for your local version of ImprovedUI and hit "Create Package."
6. Import your new ImprovedUI.pak into your load order, save it, and then load the game.
7. See if it looks good, and make any adjustments if you think it needs changing.

Making the Pull Request

Now it's time to submit this to ImprovedUI. Don't worry, most of this will just involve waiting for it to be accepted.

1. Using Gitbash, add the changed and added files to your commit: git add ImprovedUI/Public/Game/GUI
2. use git commit to make your commit.
3. use git push --set-upstream origin BRANCHNAME`, subbing BRANCHNAME for the branch name we set up earlier in this section.
4. Open your forked repo on github. There'll be a little notification that looks something like this:
5. Select "Contribute" and proceed through the steps to make a Pull Request.

Including the icons locally

We're technically done, but this last step will be good to have, just in case. At the start of the section, we dropped our icons into ImprovedUI's icons_races folder. We're going to want to do that for our mod, as well.

Now, because Community Library doesn't cover Character Creation bits and pieces, there's no need to submit a Pull Request for the icons - you'll want to keep them with your implemented mod.

1. In your ModName/Public, folder, create the following folder structure: Game\GUI\Assets\CC\icons_races
2. Drop your racial icons into icons_races.

Now you're good to go. I recommend doing one last test, and when you're sure it works, submit it to Nexus!