BG3 Forge 0.2.0

BG3 Forge 0.2.0

BG3 Forge 0.2.0 turns the project from a game-data reader into a connected
inspection, validation, and mod-authoring toolkit for Baldur's Gate 3.

BG3 Forge is a toolkit, not an in-game mod. Do not install it through
BG3 Mod Manager. Run it from PowerShell or a terminal, or embed its Python
library in another community tool.

Highlights

Find answers in the installed game

bg3forge lookup resolves stats names, UUIDs, localization handles, and
cross-references between items, spells, passives, statuses, characters,
classes, races, and progressions. Searches are forgiving, and suggestions
are commands you can copy and run directly.

bg3forge lookup Projectile_fireball_4
bg3forge lookup "Fireball"

Catch broken mods before upload

bg3forge lint MyMod.pak checks the module manifest, supported data
formats, UUIDs, localization, and internal references. Point it at an
installed game to validate references against base-game content too.

Build mods programmatically

The Mod API can create and package armor, weapons, consumables, passives,
statuses, spells, scrolls, treasure-table placement, and class spell-list
additions. Builds are deterministic, so the same source produces the same
.pak.

Use the connected BG3 data graph

The typed Python API now includes progressions, classes, races, characters,
quests, dialogs, timelines, compiled stories, treasure tables, and forward
and reverse relationships across the graph. It is designed as reusable
infrastructure for browsers, planners, bots, databases, and other modding
tools.

Download resolved game data

The release can include a patch-labeled data bundle containing SQLite,
JSON, and CSV exports plus a provenance manifest. This gives wiki editors,
theorycrafters, and tool authors usable resolved data without requiring
Python or redistributing Larian assets.

Install

Python 3.10 or newer is required.

python -m pip install "bg3forge==0.2.0"

For native-speed archive handling and every optional feature:

python -m pip install "bg3forge[all]==0.2.0"

Then verify the game installation:

bg3forge doctor

Compatibility

• Baldur's Gate 3 Patch 8 retail data has been used for end-to-end
  validation.
• Python 3.10–3.13 is tested.
• Windows, Linux, and macOS are tested.
• The core package has zero required dependencies.
• BG3 Forge reads from the game installation and writes only to paths you
  explicitly choose.

Because BG3 Forge is still pre-1.0, projects embedding it should pin the
0.2 API:

dependencies = ["bg3forge>=0.2,<0.3"]

Learn more

• Documentation and examples
• Mod-authoring guide
• Data-release format
• Full changelog
• Report a problem

bg3forge 0.1.0

First release. Everything below is validated against a full retail install
(Patch 8, 154 GB, 52 paks). See
the retail baseline
for the results and
the retail-testing guide
for reproduction instructions.

Formats

• LSPK .pak archives v15–v18: reader, writer, multi-part archives,
  LZ4/zlib/zstd entries, incremental extraction, and patch detection
• Stats .txt with using inheritance, patch layering, self-using
  overrides, and key global constants
• Localization .loca read/write support with handle-version precedence
• Node trees in LSX, LSF versions 1–7, and LSJ, parsed into a shared
  document model with format sniffing
• bg3forge convert translation between .lsf and .lsx
• Texture atlases and DDS icon extraction to PNG or WebP
• Quest journal, objectives, categories, markers, and metadata-level
  Osiris goal scripts
• Compiled Osiris stories (story.div.osi, versions 1.13–1.15), including
  metadata traversal for headers, types, functions, databases, goals,
  and rules
• Character equipment sets from Stats/Generated/Equipment.txt
• Pure-Python LZ4 block and frame codecs, giving the core library zero
  required dependencies; native speedups are available through extras

API

• Game facade that reads directly from installed paks in engine load
  order or from a previously extracted directory
• Typed models with forward and reverse relationships between items,
  passives, statuses, spells, tags, templates, quests, goals, characters,
  and equipment
• Name-addressed collections with display-name search
• Lazy indexes for dialogs, timelines, Osiris goals, and compiled stories
• Runtime-facing item templates combining canonical root templates with
  stable objects placed under module Globals and Levels
• TemplateName resolution through the root-template inheritance chain
• Selected icon export directly from game paks without an extraction step
• Deterministic JSON, SQLite, CSV, Markdown, and YAML exporters
• Character models with ability scores, localized template data,
  archetypes, passives, tags, and resolved equipment
• Journal relationships including quest objectives, categories, and
  objective markers

Command-line tools

• bg3forge doctor — installation and environment diagnostics
• bg3forge validate — full-coverage parsing with per-file failures
• bg3forge benchmark — repeatable timings, counts, and peak memory
• bg3forge search — archived-path search and directory aggregation
• bg3forge characters — character dataset export
• unpack, list, convert, patches, icons, and per-dataset export
  commands

Retail validation

• 30 readable primary paks and 1,041,877 indexed pak entries
• 16,132 resolved stats entries
• 232,876 localization handles
• 25,560 effective root templates
• 167 quests and 1,335 objectives
• All 11 shipped compiled Osiris story files parsed successfully
• 943 unique source goals found in compiled data, with none missing
• Final release benchmark: approximately 25.1 seconds and 827 MB peak RSS
• A downstream consumer validated 7,081 named items, all 146 curated item
  records, and all 994 referenced gear icon keys