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
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

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

/// @file hash_table.h
/// @brief MPQ hash table (classic V1/V2) — read, lookup, write/serialize.

#pragma once

#include <whiteout/common_types.h>

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

namespace whiteout::storages::mpq {

// ============================================================================
// Constants
// ============================================================================

/// Sentinel: empty slot (never occupied).
static constexpr u32 kHashEntryEmpty = 0xFFFFFFFF;
/// Sentinel: deleted slot (was occupied, now free for probe continuation).
static constexpr u32 kHashEntryDeleted = 0xFFFFFFFE;

// ============================================================================
// Hash Entry
// ============================================================================

/// A single 16-byte entry in the MPQ hash table.
struct HashEntry {
    u32 hashA = kHashEntryEmpty;      ///< Hash of filename (type NameA).
    u32 hashB = kHashEntryEmpty;      ///< Hash of filename (type NameB).
    u16 locale = 0xFFFF;              ///< Locale ID.
    u16 platform = 0xFFFF;            ///< Platform (always 0 in practice).
    u32 blockIndex = kHashEntryEmpty; ///< Index into block table, or sentinel.

    [[nodiscard]] bool isEmpty() const {
        return blockIndex == kHashEntryEmpty;
    }
    [[nodiscard]] bool isDeleted() const {
        return blockIndex == kHashEntryDeleted;
    }
    [[nodiscard]] bool isOccupied() const {
        return !isEmpty() && !isDeleted();
    }
};

static_assert(sizeof(HashEntry) == 16, "HashEntry must be exactly 16 bytes");

// ============================================================================
// Hash Table
// ============================================================================

class HashTable {
public:
    HashTable() = default;

    /// Parse a hash table from raw (encrypted) bytes.
    /// @param data      Raw hash table data (must be hashTableEntries * 16 bytes).
    /// @param capacity  Number of entries (from header.hashTableEntries).
    /// @return true on success.
    bool parse(std::span<const u8> data, u32 capacity);

    /// Create an empty hash table with the given capacity.
    void createEmpty(u32 capacity);

    /// Look up a filename with any locale. Returns the hash table index,
    /// or nullopt if not found.
    [[nodiscard]] std::optional<u32> lookup(const std::string& filename) const;

    /// Look up a filename with a specific locale. Returns the hash table index,
    /// or nullopt if not found.
    [[nodiscard]] std::optional<u32> lookup(const std::string& filename, u16 locale) const;

    /// Insert a new entry. Used by the writer during save() when building fresh tables.
    /// Returns the hash table index, or nullopt if the table is full.
    [[nodiscard]] std::optional<u32> insert(const std::string& filename, u16 locale,
                                            u32 blockIndex);

    /// Mark an entry as deleted. Used by the writer during save().
    /// Returns true if the entry was found and removed.
    bool remove(const std::string& filename);

    /// Mark an entry with a specific locale as deleted.
    bool remove(const std::string& filename, u16 locale);

    /// Serialize the hash table to encrypted bytes for archive output.
    [[nodiscard]] std::vector<u8> serialize() const;

    /// Direct entry access.
    [[nodiscard]] const HashEntry& entry(u32 index) const {
        return m_entries[index];
    }
    [[nodiscard]] HashEntry& entry(u32 index) {
        return m_entries[index];
    }

    /// Number of entries (capacity, always power of 2).
    [[nodiscard]] u32 capacity() const {
        return static_cast<u32>(m_entries.size());
    }

    /// Number of occupied entries.
    [[nodiscard]] u32 occupiedCount() const;

private:
    std::vector<HashEntry> m_entries;
};

} // namespace whiteout::storages::mpq