Documentation

details on creating content for the builder

In the documentation below you will find some details that help you to create your own content for the builder. You can learn to create elements from this information as well as the examples provided. A more extensive list of examples and a F.A.Q. section will be added once the documentation is finished, usually updates are added with a new release. A section with a list of elements created by other users will be available later that you will be able to use to create characters or as a reference to create your own content. As well as a section with reserved ID ranges to avoid duplicates between different homebrew content.

There is only one thing you need to start creating your own content; a text editor. You can use for example Visual Studio Code or Sublime Text which are both lightweight and easy to use. You can open a folder instead of a single file and work on your custom files in a neat environment with plenty of cool and useful features which speed up the process.

The documentation is not complete and will be finalized after v1.0. Instead it is recommended to use the examples and existing content to create elements. Use the subreddit or contact page for a quick answer if you have a specific question on how to implement something.

Quick Start

When you want to add a custom element to the builder you first have to create an XML file (.xml) that you have to copy to the custom folder located in your documents folder inside \5e Character Builder\custom. Before we get into all the parts that make up a custom files, lets just make a new race without going into much detail so we can see some fast results in the builder. We add a short description that will be displayed in the panel on the right side in the builder and leave out any other elements like ability scores and racial traits for now. We will revisit this element in a later example to add these other features until we have the entire race implemented.

Launch the text editor of your choice and create a new file, copy and paste the whole content of the code snippet below and save the file to the custom folder with a name of changeling.xml.

An elements file like this has a rootnode called elements which can contain any number of child element nodes. The value of the name attribute is how the element will be named in the builder and on character sheets. Details on the other attributes will be explained below in the documentation.

When you launch the character builder, this new race element will be loaded and added to the selection options of the race selection when you create a new character, go ahead and give it a go.

<?xml version="1.0" encoding="utf-8" ?>
<elements>
    <element name="Changeling" type="Race" source="Unearthed Arcana" id="ID_BREW_DOCS_RACE_CHANGELING">
        <description>
            <p class="flavor">Changelings are subtle shapeshifters capable of disguising their appearance.</p>
        </description>
    </element>
</elements>

Anatomy of an Element

The content of the builder is made up of elements such as races, class features, languages, and spells. Each of these elements have a set of child nodes that hold information about the implementation such as a description, specific setters unique to a cetain element, rules that grant you additional elements or increase statistics like your Armor Class or Dexterity, and rules that grant you additional elements though selection like the selection of your race.

Structure

The structure of an element is very similar for each element even though some elements may have required nodes to work while others don't require these nodes to function. As you have seen in the race element in the quick start section an element node has four attributes that each element must implement.

Attribute Description
name This is what you will see in the builder and on your character sheet and can be anything you want.
type This is used by the builder to determine for example which items need to be populated in a selection (such as Spell or Language) and where it should be placed in the build tab. There is a collection of pre-defined types here that you should choose from.
source The name of the published source, author, website, or homebrew campaign your element comes from, can be anything you want.
id

This should be a unique id. Start your id with ID_ and only use letters, numbers and underscores. An element with an id that already exists will override the existing element completely. In order to avoid duplicate elements the best practice is to make your id in the following format ID_{AUTHOR}_{SOURCE}_{TYPE}_{NAME}.

The element also has a number of child nodes that it can implement, a short description of each of these is listed below.

Node Description
supports A collection that is used to filter elements when creating a selection rule as archetypes, skill proficiencies, fighting styles, and so on.
requirements Various requirements an element can have such as a race or a minimum ability score to allow the element to be selected from a list.
description The description that shows up in the panel on the right side in the builder. This is made using basic HTML.
sheet The plain text description that will be displayed on the sheet instead of inside the builder. You can set attributes that hide the element on the character sheet or change the name displayed on the sheet.
setters A set of setters specific to certain elements such as school for spells or names (male/female) for a race.
spellcasting A simple node to indicate that this element is a spellcasting class or archetype. This will create a base for the spellcasting class including a tab and a spellcasting page.
multiclass A node on a class to indicate you can multiclass with the class.
rules A collection of rules that this element has such as statistic increases, granting additional elements, allowing a selection of a collection of elements and so on.

Supports

The supports node is mainly used to filter out certain elements for selection rules. There is no limit on how many supports an element can contain, just make sure you seperate them with a comma ,. At the moment of writing this documentation the support strings are case-sensitive, this may change in the future.

When you want to allow a player to select for example a sorcerous origin which should be of type Archetype you should create the following supports node:

<supports>Sorcerous Origin</supports>

This will allow the selection rule to find all elements of type Archetype that have a support Sorcerous Origin in them. This way the original Sorcerer class element won't need changes and allows you to add new Archetypes for classes quick. This is the case for many of the selection options such as sub races, fighting styles, languages, and so on.

Requirements

There are elements which might require you to have a certain race or a minimum ability score, this node is the place where you can set these requirements. When you need to be a changeling for a certain feat you should add the id of the changeling race element to this node like this:

<requirements>ID_BREW_DOCS_RACE_CHANGELING</requirements>

The difference with this node is that this will result into a dynamic expression that is used in the builder. It can contain AND (&& or ,) and OR (||) conditions to allow you to create your desired requirements, use the NOT (!) before any ID or block to invert the condition. When you need a requirement on an ability score you have to add a small block instead of an id like this: [dex:13]. A list of available requirement pairs is displayed below.

Here is what it should look like when you need to be a changeling with a dexterity of 13 or higher:

<requirements>ID_BREW_DOCS_RACE_CHANGELING,[dex:13]</requirements>

Predefined key/value pairs that are currently available (more will be added when needed).

Key Value
str, dex, con, int, wis, cha Any value for the ability score, not the modifier.
level Any number ranging from 1-20.
type An element type such as 'Spell'. Some feats require you to have at least one spell for example.
id The id of an element such as ID_BREW_DOCS_RACE_CHANGELING

You can encapsulate requirements with parentheses when you have multiple conditions that are valid. With the following requirement you meet the requirements when you have strength or dexterity of 13 and your class is a fighter or a ranger.

<requirements>([str:13]||[dex:13]), (ID_CLASS_FIGHTER||ID_CLASS_RANGER)</requirements>

Description

This is the description that will be displayed in the panel on the right side within the builder. This node accepts basic HTML, styling is done by the builder and can be applied by adding certain classes to certain elements. The element name is already added by default at the top of the description panel and the source url at the bottom. When the source of an element is unknown by the builder it will generate a url that will perform a search query on google with the name of the source and the name of the element.

<description>
    <p class="flavor">Changelings are subtle shapeshifters capable of disguising their appearance. Their ability to adopt other creatures’ guises makes them consummate spies and criminals.</p>
</description>

The best documentation to create descriptions is looking at (and copy/paste) the example content.

Setters

The setters is where unique values depending on the type of the element can be set with a combination of a key and a value. A race element for example might have names while a spell element has material components. Specific names depending on the type are used to populate these values in the builder.

The format for these setters is <set name="{name}">{value}</set>. Some setters that have the same name have additional attributes besides the name attribute to make sure the difference can be used by the builder. Think of a price setter with additional currency attribute to determine the type of coin used, or a name setter with a gender attribute to generate a random name based on the characters gender.

Required Setters (Race)

<setters>
    <set name="names" type="male">Adrik, Alberich, Baern, Barendd, Brottor</set>
    <set name="names" type="female">Amber, Artin, Audhild, Bardryn, Dagnal</set>
    <set name="names" type="clan">Balderk, Battlehammer, Brawnanvil, Dankil, Fireforge</set>
    <set name="names-format">$(name) $(clan)</set>
</setters>

Required Setters (Class)

<setters>
    <set name="hd">d8</set>
</setters>

Required Setters (Language)

<setters>
    <set name="speakers">Demons</set>
    <set name="script">Infernal</set>
    <set name="exotic">true</set>
</setters>

Required Setters (Spell)

<setters>
    <set name="level">3</set>
    <set name="school">Evocation</set>
    <set name="time">1 action</set>
    <set name="duration">Instantaneous</set>
    <set name="range">150 feet</set>
    <set name="hasVerbalComponent">true</set>
    <set name="hasSomaticComponent">true</set>
    <set name="hasMaterialComponent">true</set>
    <set name="materialComponent">a tiny ball of bat guana and sulfur</set>
    <set name="isConcentration">false</set>
    <set name="isRitual">false</set>
</setters>

Sheet

Much like the description node the sheet node contains the description this will be visible on the sheet. This description is just a normal plain text, not HTML. This should normally be a short description since space is limited.

The sheet node has an optional display attribute (default: true), when set to false the element will not be displayed on the character sheet. Think of simple class features that grant a skill proficiency or language. These elements are visible in other sections of the sheet and will only take up space in the features and traits section so they can be hidden.

<sheet display="false">
    <description>You gain proficiency in the Deception skill.</description>
</sheet>
<sheet display="true">
    <description>As an action, you can polymorph into any humanoid of your size that you have seen, or back into your true form. However, your equipment does not change with you. If you die, you revert to your natural appearance.</description>
</sheet>

The description should be placed inside a description child node (multiple description nodes can be added) within the sheet node. You can add a level attribute on the description node so you can have different descriptions based on your level. Inside the description you can inject values such as your level or ability modifiers. You should wrap a specific name inside $(key) for it to be replaced. A list of these names can be found below, also more information how to create custom names in the rules section.

<sheet>
    <description level="1">A bonus of $(Wisdom Modifier) to healing.</description>
    <description level="6">A bonus of $(Wisdom Modifier) to healing and damage with spells.</description>
</sheet>

Spellcasting

A simple node to indicate that this element is a spellcasting class or archetype. This will create a base for the spellcasting class including a tab and a spellcasting page, the name comes from the name attribute and is case-sensitive. Use the ability attribute to assign one of the abilities as the spellcasting ability. Include a list inside with the class name that should function as the spelllist.

<spellcasting name="Wizard" ability="Intelligence">
    <list>Wizard</list>
</spellcasting>

Exting Spellcasting List

You can extend an existing spelllist of a class by including a spellcasting node in another element. Use the name of the original spellcasting node and include the extend attribute with the value of true.

<spellcasting name="Wizard" extend="true">
    <extend>Cleric</extend>
</spellcasting>

Multiclass

Instead of creating a complete element for the multiclass class the builder clones the class element and modifies some parts, starting with the id. Include the requirements to multiclass with or into this class.

The ID_INTERNAL_GRANT_MULTICLASS element that is granted here is a requirement.

<grant type="Grants" id="ID_INTERNAL_GRANT_MULTICLASS" />
<multiclass id="ID_WOTC_PHB_MULTICLASS_PALADIN">
    <prerequisite>Strength 13 and Charisma 13</prerequisite>
    <requirements>([str:13],[cha:13])</requirements>
    <setters>
        <set name="multiclass proficiencies">Light armor, medium armor, shields, simple weapons, martial weapons</set>
    </setters>
    <rules>
        <grant type="Grants" id="ID_INTERNAL_GRANT_MULTICLASS" />
        <grant type="Proficiency" name="ID_PROFICIENCY_ARMOR_PROFICIENCY_LIGHT_ARMOR" />
        <grant type="Proficiency" name="ID_PROFICIENCY_ARMOR_PROFICIENCY_MEDIUM_ARMOR" />
        <grant type="Proficiency" name="ID_PROFICIENCY_ARMOR_PROFICIENCY_SHIELDS" />
        <grant type="Proficiency" name="ID_PROFICIENCY_WEAPON_PROFICIENCY_SIMPLE_WEAPONS" />
        <grant type="Proficiency" name="ID_PROFICIENCY_WEAPON_PROFICIENCY_MARTIAL_WEAPONS" />
    </rules>
</multiclass>

Rules

The rules node is where most of the mechanics in an elements happens. With the use of rule nodes you can increase statistics like Armor Class, Strength and Dexterity, and Hit Points. Allow the player to make a selection of elements like the selection of a primal path for a barbarian, and grant elements like skill proficiencies, languages, and class features depending on the characters level, class, or archetype.

There are three types of rules that can be applied to the rules node which are the grant rule, select rule, and the stat rule. Attributes marked with an * are required.

Grant Rule

Attribute Value
type* The type of the granted element.
id* The id of the granted element. (currently named 'name' but in the future will be renamed to id, both function in the preview)
level The level required for this grant rule. It is the first check before any other requirements and used most often.
requirements A dynamic requirements string just like the requirements node in the element. Learn More
<grant type="Language" id="ID_LANGUAGE_COMMON" />
<grant type="Class Feature" id="ID_CLASS_FEATURE_BARBARIAN_PRIMAL_PATH" level="3" />
<grant type="Class Feature" id="ID_CLASS_FEATURE_ELDRITCH_FEATURE" requirements="ID_PHB_SPELL_ELDRITCH_BLAST" />

Selection Rule

Attribute Value
type* The type of the element that you can select. This will also determine where in the build tab the selection control will be displayed.
name* The name that is displayed on the selection control in the builder.
supports A dynamic string to filter out elements with certain supports. You can also add a collection of IDs seperated by a single |, note: this way it is not possible for other custom content to be added afterwards.
level The level required for this selection rule. It is the first check before any other requirements and used most often.
requirements A dynamic requirements string just like the requirements node in the element. Learn More
number The number of selections you can make. Use this instead of creating multiple of the same selection rules unless they are on different levels or have different requirements.
default You can put the ID of an element here that if it is in the selection list it will be selected by default.
optional True of false if this selection is optional. Perhaps to select a variant on another element such as a background variant.
<select type="Proficiency" name="Skill Proficiency (Rogue)" supports="Skill,ID_CLASS_ROGUE" number="4" />
<select type="Archetype" name="Sorcerous Origin" supports="Sorcerous Origin" level="3" />
<select type="Archetype" name="Another Sorcerous Origin" supports="ID_ORIGIN_A|ID_ORIGIN_B" level="3" />

Statistics Rule

Attribute Value
name* The name of the statistic value. (case-sensitive, will be all lowercase in the future)
value* The value which can be a number or the name of another statistic. ('Wisdom Modifier' or 'Proficiency')
bonus When there are multiple rules that apply a certain bonus to the same statistic the name here is used to compare all values and take the highest one, so they don't stack. Use the name 'base' when assigning base such as speed or fly speed.
equipped A dynamic string that contains certain formatting for checking equipped items such as armor, shields, weapons.
level The level required for this statistics rule.
requirements A dynamic string that can contain a requirement on certain elements when the level attribute alone is not enough. This is the same as the requirements node in the element.
inline True when the statistic is specifically for replacing inline sheet descriptions that can't be calculated (non-numeric).
<stat name="Speed" value="10" equipped="![armor:heavy]" />
<stat name="speed:fly" value="30" bonus="base" equipped="![armor:heavy]" />
<stat name="Acrobatics Misc" value="Proficiency" bonus="Expertise" />
<stat name="feature:damage type" value="Force" inline="true" />

Element Reference Types

Race, Racial Trait, Sub Race, Race Variant, Class, Class Feature, Archetype, Archetype Feature, Background, Background Feature, Background Variant, Ability Score Improvement, Language, Proficiency, Feat, Feat Feature, Alignment, Spell, Item, Option, Deity, Size, Vision, Companion, Companion Feature, Grants


Statistic Reference Names

Case-senstive, will be all lowercase in the future.

AC, ac:natural, HP, Speed, speed:fly, speed:swim, speed:climb, speed:burrow, Initiative, Proficiency, Proficiency Half, HP, Strength, Strength Modifier, Strength Saving Throw Proficiency, Strength Saving Throw Misc , Acrobatics, Acrobatics Proficiency, Acrobatics Misc, Acrobatics Passive, level:wizard, level:wizard:half, level:wizard:half:up

Developer Mode

When you plan to create custom content you can enable the developer mode in the builder. This section has no priority so currently it will not look as nice as the main application.

When you make use of the developer mode it is recommended that you create characters in the default mode. The normal mode is faster because it does not run extra operations or create debugging logs in the background.

Enable Developer Mode

You can start the character builder in developer mode by modifiying the shortcut to the builder. Modify the existing or create a new shortcut on your desktop, right click it, and go to properties. In the target textbox add dev after the last quote so it will look like this; ~\Aurora Builder.exe" dev. When you run the builder from this shortcut it will enable developer mode and add new button in the statusbar that will open a developer panel.

Elements Browser

This is the place to browse through every element loaded by the builder. When you're looking for the ID of a language or what support string is required for a dwarven subrace, this is the way to do so since there are too many to be listed and kept up to date on the website. Also the custom elements that are loaded can be looked at from within these developer tools.