dnd5e-character-builder

Build, level up and check D&D 2024 (SRD 5.2.1) character sheets in Python.

A sheet written by a person or a model is free text: "Rogue (Arcane Trickster)", "Shield — level 1, prepared". This library reads it against the rules, lists every problem at once, writes in the numbers the rules derive, and says what the character may still pick now or at the next level. It sits on nat20's rules engine and SRD corpus; nat20 decides whether a build is constructible and derives its HP, AC, saves and slots. This library adds the parts of a sheet nat20 takes as given: class spell lists, prepared and cantrip counts, wizard spellbooks, feat slots, choice counts, skills and ability-score generation.

pip install dnd5e-character-builder

Python 3.14 or later.

Use

from dnd5e_character_builder import Feat, Sheet, check, fill, level_up, options

sheet = Sheet.model_validate({
    'name': 'Ana',
    'species': 'Human',
    'class': 'Fighter',
    'level': 4,
    'subclass': 'Champion',
    'background': 'Soldier',
    'abilities': {'str': 17, 'dex': 15, 'con': 14, 'int': 8, 'wis': 12, 'cha': 10},
    'skills': ['Athletics', 'Intimidation', 'Perception', 'Survival', 'Acrobatics'],
    'feats': ['Savage Attacker', 'Alert', Feat(name='Grappler', level=4)],
    'choices': ['Defense'],
    'inventory': ['Chain Mail', 'Longsword', 'Shield'],
})

sheet = fill(sheet)            # max_hp, ac, saving_throws and spell_slots from nat20
for issue in check(sheet):     # every problem at once
    print(issue.severity, issue.code, issue.message)

options(sheet)                 # every pick at this level (subclass, feature choices, feat slots, skills, spells) and what fills it
level_up(sheet, 5)             # what level 5 gives automatically and which picks it makes due

level_up and options report; neither changes the sheet. Write the picks, then run fill and check.

build_spec(sheet) and derive(sheet) give nat20's CharacterBuildSpec and DerivedSheet for a sheet, for hosts that run nat20 combat.

The sheet

Issues

Each Issue has a stable code, a severity (error breaks the rules, warning is likely wrong, info is a note), the sheet field, a message and a detail dict.

Spells a character has without preparing them do not count against the class table: species and subclass grants, spells a feature's own text grants ("You always have the Hunter's Mark spell prepared"), the Circle of the Land table the sheet matches best, Mystic Arcanum, Magic Initiate, and the College of Lore's Magical Discoveries.

Homebrew

load_content(*paths) layers YAML or JSON files (or folders of them) over the SRD; pass the result as content= to any call. A file holds nat20-schema entries and this library's tables:

subclasses: [...]        # nat20 schema; also classes, species, backgrounds, feats, features, spells
spell_lists:             # class -> spell level -> spells added to its list; a name with no entry is known by name and level
  wizard: {1: [Chromatic Orb], 2: [Dragon's Breath]}
subclass_spells:         # always-prepared spells by class level
  oath-of-glory: {3: [Guiding Bolt, Heroism], 5: [Enhance Ability, Magic Weapon]}
subclass_spell_choices:  # one table per option, as Circle of the Land
  circle-of-the-reef: {shallows: {3: [Fog Cloud, Water Breathing]}}
class_tables:            # cantrips and prepared per level, 20 each; a casting subclass also names progression and spell_list
  eldritch-knight: {cantrips: [...], prepared: [...], progression: third, spell_list: wizard}
aliases:
  subclasses: {glory: oath-of-glory}

A path may also be a mapping of the same shape. load_content(loader=...) builds on your own nat20 AssetLoader instead of nat20's bundled corpus.

Loading refuses anything the library could not check, with a ContentError naming it: a spellcasting class without a table or spell list, a subclass with a Spellcasting feature and no table, a subclass whose spells feature grants no spells, a spell listed at the wrong level, an alias to nothing. Entries without nat20 provenance get a placeholder one so they pass nat20's schema.

Limits

Single class only; see BACKLOG.md for the rest.

Data and attribution

• Rules engine and SRD corpus: nat20 (dnd5e-engine, dnd5e-srd-data), MIT.
• Class spell lists and the Cantrips and Prepared Spells columns: 5e-SRD-Spells.json and 5e-SRD-Levels.json from 5e-database (src/2024/en, commit 6f6299e), MIT, vendored unchanged in src/dnd5e_character_builder/data/5e-database with its licence. Two columns are corrected from the SRD in data/srd.yaml.
• This work includes material from the System Reference Document 5.2.1 ("SRD 5.2.1") by Wizards of the Coast LLC, available at https://www.dndbeyond.com/srd. The SRD 5.2.1 is licensed under the Creative Commons Attribution 4.0 International License, available at https://creativecommons.org/licenses/by/4.0/legalcode.

This library's code is MIT; see LICENSE.

Develop

uv sync
uv run ruff format --check src tests && uv run ruff check src tests && uv run mypy src tests && uv run pytest

Release

Bump version in pyproject.toml, commit, then git tag v<version> && git push origin v<version>. The release.yml workflow runs the checks and publishes to PyPI through Trusted Publishing.