whiteoutlib 0.1.1

Read and write Blizzard game assets: models (MDX, M2, M3), textures (BLP, DDS, PNG, ...) and archives (CASC, MPQ).
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

// SPDX-License-Identifier: BSD-3-Clause
// Copyright (c) 2026 Fernando Sahmkow

/// @file writer.h
/// @brief MPQ archive writer — assembles a complete MPQ from tables + file data.

#pragma once

#include <whiteout/common_types.h>

#include "codecs/compression.h"
#include "file_data.h"
#include "special_files.h"
#include "tables/block_table.h"
#include "tables/hash_table.h"
#include "tables/header.h"

#include <span>
#include <string>
#include <vector>

namespace whiteout::interfaces {
class WorkerPool;
}

namespace whiteout::storages::mpq {

/// Describes a file to be written into the new archive.
struct WriteEntry {
    std::string filename;
    u16 locale = 0;

    /// If rawData is non-empty, this is a new/modified file from the overlay.
    std::vector<u8> rawData;
    CompressionFlag compression = CompressionFlag::kZlib;
    bool encrypt = false;
    bool singleUnit = false;

    /// If rawSectors is non-empty, this is a raw copy from the source archive
    /// (compressed sectors copied as-is, no re-encoding needed).
    std::span<const u8> rawSectors;
    BlockEntry sourceBlock{}; ///< Original block entry (for raw copies).
};

/// Write a complete MPQ archive to a byte buffer.
///
/// The writer:
/// 1. Writes the MPQ header.
/// 2. Writes file data sequentially (raw sector copies + freshly encoded files).
/// 3. Writes (listfile) and (attributes) as regular files.
/// 4. Writes encrypted hash table.
/// 5. Writes encrypted block table (+ hi-block table if V2+).
/// 6. Updates header with final offsets and sizes.
///
/// @param header    Template header (version, sector size, etc.).
/// @param entries   Files to write.
/// @param hashTableCapacity  Hash table size (power of 2).
/// @return The complete archive as a byte vector.
[[nodiscard]] std::vector<u8> writeArchive(const MpqHeader& header,
                                           const std::vector<WriteEntry>& entries,
                                           u32 hashTableCapacity,
                                           interfaces::WorkerPool* pool = nullptr);

} // namespace whiteout::storages::mpq