Skip to main content
Pre-release

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

bg3-core

Foundational runtime, binary parsers, cross-platform path resolution, and mod.io REST API client for the Baldur's Gate 3 Mod Studio workspace.


Domain Architecture & Scope

bg3-core serves as the foundational, leaf-level dependency package in the monorepo DAG. It is designed to be completely independent of higher-level domain packages (bg3-authoring and bg3-theorycraft), providing low-level binary engines and runtime utilities that require zero external binary tools (such as LSLib's divine.exe, Wine, or .NET runtimes).

graph TD
    Authoring["bg3-authoring"] --> Core["bg3-core"]
    Theorycraft["bg3-theorycraft"] --> Core["bg3-core"]
    CLI["bg3 CLI Router"] --> Core

Core Modules & Exported Interfaces

Module Core Responsibility Key Exported Symbols
bg3_core.larian_parsers Larian binary formats, version encoding, and localization encode_version64(), decode_version64(), parse_loca_bytes(), compile_xml_bytes_to_loca(), split_larian_items()
bg3_core.lspk Pure-Python LSPK v18 archive reader, builder, and unpacker LspkArchive, build_lspk_archive(), lz4_block_decompress(), lz4_frame_or_block_decompress(), decompress_pak_file_data()
bg3_core.save_inspector Save game metadata extraction, AST audit, and mod pruning extract_save_metadata(), audit_against_modsettings(), prune_missing_mods_from_save()
bg3_core.manage_saves Savegame discovery, backup, retention purging, and rescue discover_save_games(), handle_clean_missing()
bg3_core.env_paths Cross-platform state, cache, config, and game path detection get_xdg_config_home(), get_xdg_cache_home(), get_xdg_data_home(), detect_bg3_appdata_dirs(), detect_bg3_install_dir()
bg3_core.cli_common Stream separation, POSIX exit codes, and JSON envelopes OutputEmitter, ConsoleColor, ExitCode, format_json_response(), confirm_action()
bg3_core.modio_client Authenticated mod.io v1 REST client ModioClient, ModioError, resolve_modio_token()
bg3_core.tools Dynamic CLI argument parser introspection and registry build_parser_ast_registry(), search_tools(), verify_registry(), audit_skills()
bg3_core.cli Central unified router for all workspace domains main(), build_parser(), dispatch_command()

CLI Console Entrypoint

This package registers the primary console script for the entire studio:

[project.scripts]
bg3 = "bg3_core.cli:main"

Common Commands Driven by bg3-core:

  • bg3 tools list — Discover all registered tools across packages.
  • bg3 tools search <query> — Search tools by semantic intent.
  • bg3 tools info <tool> — Inspect tool arguments and schemas.
  • bg3 tools verify --audit-skills — Programmatic health audit of agent skills.
  • bg3 modio search <query> — Search remote community mods on mod.io.
  • bg3 modio sync — Synchronize subscribed mods and download .pak packages.
  • bg3 loadorder list — Inspect active modsettings.lsx load order.
  • bg3 save inspect latest — Inspect save metadata and audit mod requirements.
  • bg3 save clean-missing — Prune missing mods to rescue corrupted saves.

Cross-Platform Storage Architecture

All state directories comply strictly with the XDG Base Directory specification on Linux/macOS and APPDATA specifications on Windows:

  • Configuration: $XDG_CONFIG_HOME/bg3/env (or %APPDATA%\bg3\env)
  • Cache: $XDG_CACHE_HOME/bg3/ (or %LOCALAPPDATA%\bg3\)
  • User Content: $XDG_DOCUMENTS_DIR/BG3_Mod_Studio/Mods/
  • Game VFS: Automatically detects Steam Native, Proton (compatdata/1086940/pfx), WSL, and Windows installations.

Metadata

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

Built distribution (wheel)

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

Total release size: 321.3 kB

Release files / bg3_core-1.0.0b1.tar.gz

Download URL bg3_core-1.0.0b1.tar.gz
Size 147.4 kB
Tags Source
SHA-256 checksum
How to use checksums
9a29cb747ccf0a3abab40db5df3febe187671026fa010b24c5f5774e4de09322
BLAKE2b-256 checksum
How to use checksums
0da5e6ba1316eb314ac61f0c8bcbb35cf83d74e3a847cf40e260016a9f6b7899
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

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

Download URL bg3_core-1.0.0b1-py3-none-any.whl
Size 173.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6f767779977eafa05bd218fc206bcb5ca95fa99bb7842a8a6964783724601081
BLAKE2b-256 checksum
How to use checksums
944623688de211ce27ebdeef7752b84e50f1e19ed64893d4c92d8f85560e4b13
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

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