MacLarian

A pure-Rust implementation of a [M]acOS-focused Larian file format library and toolkit for Baldur's Gate 3 file handling and modding.

[!NOTE] This crate is in active development (0.x). The API may change between releases.

Supported Formats

Format	Read	Write	Description
PAK	Yes	Yes	Extract, create, and list game asset packages
LSF/LSX/LSJ	Yes	Yes	Binary, XML, and JSON document formats
LOCA	Yes	Yes	Localization (language) files
GR2	Yes	Yes	Granny2 mesh files for BG3
glTF/GLB	Yes	Yes	3D model import/export for Blender
DDS/PNG	Yes	Yes	Texture conversion
GTS/GTP	Yes	Yes	GTS/GTP streaming virtual texture extraction/creation

[!CAUTION] Creating custom virtual textures (.gts/.gtp files) is not recommended for macOS because they need to be injected into the game using the BG3 Script Extender, which is Windows-only. BG3SE-macOS is a macOS port of the original Windows version, but it's in active development and custom virtual textures may not be fully supported yet.

Platform Support

OS	Compatibility
macOS (Apple Silicon)	Yes (Built with M2 Max)
macOS (Intel)	Currently Testing (Intel iMac)
Windows 10 (Boot Camp)	Currently Testing (Intel iMac)
Windows 11	Currently Testing
Linux	Unknown

The following are assumed to be the default BG3 install locations:

macOS: ~/Library/Application Support/Steam/steamapps/common/Baldurs Gate 3/Baldur's Gate 3.app/Contents/Data
Windows: C:\Program Files (x86)\Steam\steamapps\common\Baldurs Gate 3\Data
Linux: ~/.steam/steam/steamapps/common/Baldurs Gate 3/Data

Note: MacLarian should work on all platforms. However, automatic BG3 game installation detection (GameDataResolver::auto_detect()) is limited to the paths above. If BG3 is installed in a different location (specifically the \Data subfolder), use --bg3-path <path> to specify the BG3 install folder manually.

MacLarian Library

To install the MacLarian library as a dependency crate, add this to your Cargo.toml:

[dependencies]
maclarian = "0.1"

If you don't want the CLI and only want the library, add this to your Cargo.toml:

[dependencies]
maclarian = { version = "0.1", default-features = false }

use maclarian::pak::PakOperations;

// List contents of a PAK file
let files = PakOperations::list("Shared.pak")?;
println!("Found {} files", files.len());
for path in &files {
    println!("{path}");
}

// Extract an entire PAK file
PakOperations::extract("Shared.pak", "output/")?;

// Read a specific file from a PAK without extracting
let data = PakOperations::read_file_bytes("Shared.pak", "Public/Shared/meta.lsx")?;

use maclarian::converter::convert_lsf_to_lsx;

// Convert LSF (binary) to LSX (XML) file
convert_lsf_to_lsx("meta.lsf", "meta.lsx")?;

use maclarian::converter::gr2_gltf::convert_gr2_bytes_to_glb;

let gr2_data = std::fs::read("model.GR2")?;
let glb_data = convert_gr2_bytes_to_glb(&gr2_data)?;
std::fs::write("model.glb", glb_data)?;

use maclarian::prelude::*;

// Now you have access to:
// - PakOperations, LsfDocument, LsxDocument, LsjDocument
// - VirtualTextureExtractor, GtsFile, GtpFile
// - Error, Result, and more

[!IMPORTANT] Documentation of the full API is in the MacLarian docs.rs →

MacLarian CLI

To use MacLarian as a CLI tool (assuming Rust is already installed):

cargo install maclarian

Run with:

maclarian <command>

Commands Overview

Command	Description
`pak`	List, extract, and create PAK files
`convert`	Convert between file formats (LSF↔LSX↔LSJ, LOCA↔XML, DDS↔PNG)
`gr2`	Pair and extract textures for GR2 files, convert GR2↔glTF/GLB
`vt`	Virtual texture (GTS/GTP) extraction and creation
`mods`	Mod utilities (validation, info.json)
`loca`	Search within LOCA localization files

[!IMPORTANT] The full list of CLI commands is in the wiki →

License

This project is licensed under the PolyForm Noncommercial License 1.0.0.

Some files are dual-licensed under MIT/Apache-2.0 from upstream projects. See the LICENSE file for details.

Credits

Most of the functionality in MacLarian is derived from:

LSLib by Norbyte (MIT)
xiba by saghm (Apache-2.0)
Knit by Legiayayana (MIT)

maclarian 0.1.2