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.pakpackages.bg3 loadorder list— Inspect activemodsettings.lsxload 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.