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 page, and have pulled down your own copy of the Community Library.

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.

//TODO

Race Entry

First thing's first, we need to work on our races.lsx entry.

//TODO

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!