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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.