bg3rustpaklib 0.1.0

A Rust library for reading and extracting Baldur's Gate 3 PAK files
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

# bg3rustpaklib

A Rust library for reading, extracting, and creating Baldur's Gate 3 PAK files.

## Overview

This library provides functionality for working with Larian Studios' PAK (LSPK) archive format used in Baldur's Gate 3. It is similar to [lslib](https://github.com/Norbyte/lslib) but written in Rust.

## Features

- **Read PAK files** - Supports versions 15, 16, and 18 (BG3 format)
- **List and search files** - Find files by pattern or search within packages
- **Extract files** - Extract individual files or entire packages to disk
- **Create PAK files** - Build new packages from directories
- **Compression support** - LZ4 and Zstd decompression
- **Solid archives** - Support for solid archive handling
- **Async API** - Optional async support via `async` feature

## Usage

Add to your `Cargo.toml`:

```toml
[dependencies]
bg3rustpaklib = "0.1"
```

### Basic Example

```rust
use bg3rustpaklib::{Package, PackageSearch};

fn main() -> bg3rustpaklib::Result<()> {
    // Open a PAK file
    let package = Package::open("Game.pak")?;

    // Get package metadata
    let metadata = package.metadata();
    println!("Package version: {}", metadata.version);
    println!("File count: {}", metadata.file_count);

    // List all files
    for file in package.files() {
        println!("{} ({} bytes)", file.name(), file.size());
    }

    // Find files by pattern
    let lsf_files = package.find("**/*.lsf");
    println!("Found {} .lsf files", lsf_files.len());

    // Extract a specific file
    if let Some(file) = package.get("Public/Game/GUI/Assets/Tooltips/tooltip.lsf") {
        let contents = package.read_file(file)?;
        println!("File size: {} bytes", contents.len());
    }

    // Extract all files to a directory
    package.extract_all("output/")?;

    Ok(())
}
```

### Async Support

Enable the `async` feature for async APIs:

```toml
[dependencies]
bg3rustpaklib = { version = "0.1", features = ["async"] }
```

```rust
use bg3rustpaklib::AsyncPackage;

#[tokio::main]
async fn main() -> bg3rustpaklib::Result<()> {
    let package = AsyncPackage::open("Game.pak").await?;
    let metadata = package.metadata().await;
    println!("File count: {}", metadata.file_count);
    Ok(())
}
```

## Command-line Tools

Several example tools are included:

### dump_header

Dumps hex view of the first and last 64 bytes of a PAK file:

```bash
cargo run --example dump_header path/to/file.pak
```

### detailed_dump

Shows detailed package information including file list:

```bash
cargo run --example detailed_dump path/to/file.pak
```

### compare_paks

Compares multiple PAK files and shows their metadata:

```bash
cargo run --example compare_paks path/to/pak1.pak path/to/pak2.pak
```

### repack_test

Demonstrates extracting and repacking a PAK file:

```bash
cargo run --example repack_test input.pak output.pak
```

## Building

```bash
# Build the library
cargo build

# Build with async support
cargo build --features async

# Run tests
cargo test

# Build examples
cargo build --examples
```

## API Reference

See [docs.rs](https://docs.rs/bg3rustpaklib) for full API documentation.

## License

MIT License - see LICENSE file for details.

## Credits

Inspired by [lslib](https://github.com/Norbyte/lslib) by Norbyte.