Skip to main content
Pre-release

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

bg3-authoring

Mod authoring, asset scaffolding, static diagnostics, and packaging toolchain for the Baldur's Gate 3 Mod Studio workspace.


Domain Architecture & Scope

bg3-authoring provides end-to-end tooling for creating, linting, packaging, and debugging custom Baldur's Gate 3 mods. It generates Patch 8 compliant Larian XML structures, deterministic UUIDv4 identifiers, and localized string handles (h...g...), enforcing clean separation between authored source mods and the game's Virtual File System (VFS).

flowchart TD
    Scaffold["14 Asset Generators\n(bg3_authoring.scaffold_*)"] --> ModDir["Mods/authored/<ModSlug>/"]
    ModDir --> Diagnostics["Static Diagnostics & Linter\n(validate_mod, check_mod_conflicts)"]
    Diagnostics --> Packaging["LSPK v18 Packager\n(packaging.pack_mod_pak)"]
    Packaging --> VFS["Game VFS Sync\n(packaging.sync_game_data)"]

Subpackages & Core Capabilities

1. Asset Scaffolding Generators

14 specialized generator modules creating standard Larian engine structures:

  • create_mod_scaffold.py: Generates the canonical 4-root mod directory layout (Mods/, Projects/, Public/, Localization/).
  • scaffold_class_description.py: Scaffolds classes, subclasses, ProgressionDescriptions, and parent progression wiring.
  • scaffold_feat.py: Generates feats, FeatDescriptions, and localization string tables.
  • scaffold_spell_list.py: Scaffolds standalone SpellLists and PassiveLists.
  • scaffold_level_map.py: Configures LevelMapValues scaling curves across character levels 1–20.
  • scaffold_action_resource.py: Creates custom action points, spell slots, and resource replenish conditions.
  • scaffold_progression_node.py: Appends level-up progressions into Progressions.lsx.
  • scaffold_root_template.py: Generates 3D GameObject root templates for items and equipment.
  • scaffold_stat_entry.py: Scaffolds Weapons, Armor, Spells, Passives, and StatusData text entries.
  • scaffold_icon_uvs.py: Computes texture atlas UV coordinates for custom spell and item icons.

2. Diagnostics & Compatibility (bg3_authoring.diagnostics)

  • validate_mod.py: Deep static validation checking XML/LSX syntax, UUID collisions, missing string handles, and required folder layouts.
  • check_mod_conflicts.py: Cross-mod progression collision detector auditing vanilla and community mod overrides.
  • diagnose_toolkit_logs.py: Automated triage of Larian Toolkit and engine runtime crash logs with actionable fix recommendations.

3. Packaging & Synchronization (bg3_authoring.packaging)

  • pack_mod_pak.py: Pure-Python LSPK v18 binary compiler that writes 40-byte headers, compresses files using LZ4 block compression (LSPK v18), compiles XML localization into binary .loca, and outputs deployable .pak archives.
  • sync_game_data.py: Idempotent differential file synchronizer that mirrors mod assets into the game's Data/ directory for live in-engine playtesting.

CLI Console Entrypoint

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

[project.scripts]
bg3-mod = "bg3_authoring.cli:main"

Common Commands:

  • bg3 mod scaffold <asset-type> --mod <ModSlug> ... — Scaffold new game assets.
  • bg3 mod validate <ModSlug> — Run strict pre-commit validation.
  • bg3 mod conflict <path> --against-library — Check progression collisions.
  • bg3 mod pack <ModSlug> --publish-local — Compile LSPK .pak and deploy to local mods folder.
  • bg3 mod sync-game --mods <ModSlug> [--watch] — Hot-reload source files into the game runtime.
  • bg3 save inspect latest — Audit save-game mod dependencies before launching the game.

Metadata

Release files for bg3-authoring 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-authoring 1.0.0b1
File Size Uploaded Provenance Actions
bg3_authoring-1.0.0b1.tar.gz 86.9 kB Without provenance Details for bg3_authoring-1.0.0b1.tar.gz

Built distribution (wheel)

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

Total release size: 219.7 kB

Release files / bg3_authoring-1.0.0b1.tar.gz

Download URL bg3_authoring-1.0.0b1.tar.gz
Size 86.9 kB
Tags Source
SHA-256 checksum
How to use checksums
2858bb7b02a6ab800a275c40d086d19afdd195f6cf6a8a6584b033a2987799a7
BLAKE2b-256 checksum
How to use checksums
dc9178fbf6751c752232c53b77aef3586047d6c25bf4cf708e001ce9fd5485f0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

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

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

Security for bg3-authoring 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