Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

bg3-theorycraft

Combat modeling, multiclass build simulation, and theorycrafting engine for the Baldur's Gate 3 Mod Studio workspace.


Domain Architecture & Scope

bg3-theorycraft enables deep mechanical analysis of Baldur's Gate 3 character builds across levels 1 through 20. It models D&D 5e / Larian rulesets including action economy, resource budgets, spell slot progression matrices, hit probabilities, and Damage-Per-Round (DPR) distributions against varying target Armor Classes.

flowchart LR
    Config["Build Spec\n(--class paladin:6,sorcerer:14)"] --> Simulator["simulate_build_synergy.py"]
    Gear["Cataloged Mod Gear\n(bg3 query)"] --> Simulator
    Simulator --> Output["Markdown Build Guide\n& DPR Progression Table"]

Core Capabilities

1. Multiclass Synergy & DPR Simulation (simulate_build_synergy.py)

  • Progression Modeling: Simulates 1–20 character level progression across single-class and complex multiclass combinations (e.g. Paladin 6 / Sorcerer 14).
  • Damage-Per-Round (DPR) Calculations: Computes expected sustained and burst DPR values against target Armor Classes ranging from AC 10 through AC 25.
  • Action Economy & Resource Budgets: Models standard Actions, Bonus Actions, Reactions, and class-specific action resources (Channel Oath, Superiority Dice, Sorcery Points, Ki).
  • Hit Probability & Crits: Evaluates advantage/disadvantage mechanics, critical hit ranges (e.g. Champion, equipment boosts), and Savage Attacker dice distributions.
  • Spell Slot Matrices: Computes multiclass spellcaster levels and slot allocations according to 5e rules.

2. Best-in-Slot (BiS) Community Gear Integration

Interfaces with bg3_core.query_mod_database to analyze cataloged equipment from community mods:

  • Search equipment by stat bonuses, spell save DC increases, extra attacks, and unique passives.
  • Map item synergies to turn-1 opening combat sequences.

CLI Console Entrypoint

This package registers the bg3-build console script (also routed via the main bg3 router):

[project.scripts]
bg3-build = "bg3_theorycraft.cli:main"

Common Commands:

  • bg3 build simulate --class paladin:6,sorcerer:14 — Generate level 1–20 multiclass synergy table.
  • bg3 build simulate --class fighter:12 --gear "GWM,Balduran Greatsword" --dpr — Calculate DPR across AC 10–25.
  • bg3 query "SpellSaveDC" — Query cataloged mod items providing Spell Save DC bonuses.

Metadata

Release files for bg3-theorycraft 1.0.0b1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bg3-theorycraft 1.0.0b1
File Size Uploaded Provenance Actions
bg3_theorycraft-1.0.0b1.tar.gz 10.7 kB Without provenance Details for bg3_theorycraft-1.0.0b1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for bg3-theorycraft 1.0.0b1
File Interpreter ABI Platform Actions
bg3_theorycraft-1.0.0b1-py3-none-any.whl Python 3 none any Details for bg3_theorycraft-1.0.0b1-py3-none-any.whl

Total release size: 24.2 kB

Release files / bg3_theorycraft-1.0.0b1.tar.gz

Download URL bg3_theorycraft-1.0.0b1.tar.gz
Size 10.7 kB
Tags Source
SHA-256 checksum
How to use checksums
ebe9de3ca8907d891358f4825937d84ed7072e769a0a28da785b7203aeabf972
BLAKE2b-256 checksum
How to use checksums
0558c490ec85f6c5520493b77fdfb60de57219e3ad43043a59d0d5635d54e995
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / bg3_theorycraft-1.0.0b1-py3-none-any.whl

Download URL bg3_theorycraft-1.0.0b1-py3-none-any.whl
Size 13.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3d68aef0f3e15dcf0938aad6fd8548eb494da1ba118d7cab640f1cf397bb6c5c
BLAKE2b-256 checksum
How to use checksums
5ee5a3abc394cfb237501a41901a3cb3b48ab39595cff5604b7e1fde10aae93e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for bg3-theorycraft 1.0.0b1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page