wowlib Namespace Reference

Namespaces
namespace	audit
namespace	builds
namespace	db
namespace	detail
namespace	formats
namespace	fs
namespace	lang
namespace	versions

Classes
struct	ClientVersion
struct	Error
	A wowlib operation failure: a machine-readable code, a human-readable message, and the originating native (StormLib/CascLib/OS) error value when one exists. More...
struct	FileDataID
struct	FileKey

Typedefs
using	FileBuffer = std::vector<std::byte>
	Owning byte buffer for file contents read out of a client storage.
template<typename T>
using	Result = std::expected<T, Error>
	Every fallible wowlib operation returns Result<T>; bindings translate the error branch into a target-language exception.
using	SharedMutex = std::shared_mutex

Enumerations
enum class	StorageKind { Mpq , Casc }
enum class	ClientFlavor { Retail , Classic , ClassicEra , Anniversary }
enum class	Locale {   enUS , enGB , deDE , frFR ,   ruRU , esES , esMX , koKR ,   zhCN , zhTW , ptBR , itIT }
enum class	ErrorCode : std::uint32_t {   StorageOpenFailed , ArchiveOpenFailed , StorageNotOpen , FileNotFound ,   PathNotResolvable , FdidNotResolvable , ListfileParseError , ListfileIoError ,   FdidSpaceExhausted , DuplicatePath , InvalidPath , IoError ,   EncryptedContent , NotSupported , NotImplemented , BackendError ,   ChunkTruncated , ChunkSizeMismatch , ChunkMissing , OffsetOutOfBounds ,   InvalidEntityState , FormatVersionMismatch , UnsupportedClientVersion , TableTruncated ,   TableMagicUnknown , SchemaMismatch , SchemaBlobInvalid , TableUnknown }
	Machine-readable failure category carried by every Error. More...
enum class	Expansion {   Vanilla , Tbc , Wotlk , Cata ,   Mop , Wod , Legion , Bfa ,   Shadowlands , Dragonflight , TheWarWithin }

Functions
std::ostream &	operator<< (std::ostream &out, const ClientVersion &version)
	render version as "major.minor.patch.build", with the flavor appended when it is not Retail ("1.15.9.69109 (ClassicEra)") — a Classic version is unreadable without it, since the tuple alone says nothing about the client.
std::string_view	localeCode (Locale locale)
	The four-letter code of locale ("enUS", ...) as used in MPQ locale directory and archive names.
std::optional< Locale >	localeFromCode (std::string_view code)
	Parse a four-letter locale code.
std::uint32_t	cascLocaleFlag (Locale locale)
	The CASC_LOCALE_* bit of locale for CascOpenStorage/CascOpenFile locale masks.
constexpr std::string_view	to_string (ErrorCode code)
	The enumerator spelling of code, obtained via reflection.
std::string	to_string (const Error &error)
	The human-readable rendering of error: its code spelling, its message, and the native error value when there is one.
std::unexpected< Error >	makeError (ErrorCode code, std::string message, std::uint32_t nativeError=0)
	Shorthand for constructing the error branch of a Result.
constexpr ClientVersion	toClientVersion (Expansion expansion)
	The last-minor-of-major client version wowlib targets for this expansion (the versions constant).
constexpr std::optional< Expansion >	toExpansion (ClientVersion version)
	The expansion whose targeted release is exactly this version.
constexpr std::optional< Expansion >	expansionOf (ClientVersion version)
std::string	normalizePath (std::string_view path)
	Canonicalize a client-internal file path.
std::string	toNativeRelative (std::string_view canonical)
	Convert a canonical path to a forward-slash relative path for use on the native filesystem (project-directory overlay on POSIX).
template<typename E> requires std::is_enum_v<E>
constexpr std::string_view	enumName (E value)
	The enumerator name of value, straight from reflection — no handwritten stringification tables anywhere in wowlib.

Typedef Documentation

FileBuffer

using wowlib::FileBuffer = std::vector<std::byte>

Owning byte buffer for file contents read out of a client storage.

A plain vector: cheap to move, maps onto the Python buffer protocol, and has no lifetime coupling to storage handles (both StormLib and CascLib require copying out of the archive anyway). A zero-copy arena can replace this alias later without touching call sites.

Definition at line 16 of file buffer.hpp.

Result

template<typename T>

using wowlib::Result = std::expected<T, Error>

Every fallible wowlib operation returns Result<T>; bindings translate the error branch into a target-language exception.

Template Parameters

T	the success payload (void for pure effects).

Definition at line 100 of file error.hpp.

SharedMutex

using wowlib::SharedMutex = std::shared_mutex

Definition at line 47 of file shared_mutex.hpp.

Enumeration Type Documentation

ClientFlavor

enum class wowlib::ClientFlavor

strong

Enumerator
Retail	The progression client ('wow').
Classic	The Classic progression line ('wow_classic'): BCC 2.5, WotLK 3.4, Cata 4.4, MoP 5.5.
ClassicEra	Classic Era ('wow_classic_era'): the 1.13-1.15 vanilla realms.
Anniversary	The Anniversary realms ('wow_anniversary').

Definition at line 25 of file client_version.hpp.

ErrorCode

enum class wowlib::ErrorCode : std::uint32_t

strong

Machine-readable failure category carried by every Error.

Not welded — the Python rod instead generates one exception class per enumerator (the class identity IS the code); Lua errors carry the spelling as a message prefix.

Enumerator
StorageOpenFailed	The client storage (MPQ chain / CASC) failed to initialize.
ArchiveOpenFailed	A single archive within an MPQ chain failed to open.
StorageNotOpen	Operation on a closed or moved-from storage.
FileNotFound	The file exists nowhere in the overlay or storage.
PathNotResolvable	No FileDataID is known for the given path (listfile miss).
FdidNotResolvable	No path is known for the given FileDataID.
ListfileParseError	Malformed listfile CSV content.
ListfileIoError	The listfile could not be read or written.
FdidSpaceExhausted	The custom FileDataID allocator ran out of u32 space.
DuplicatePath	Registering a path that already has a FileDataID.
InvalidPath	A path that cannot be normalized/used.
IoError	Generic filesystem I/O failure (project directory).
EncryptedContent	Content is behind an unknown TACT encryption key.
NotSupported	Operation not supported by this backend/provider.
NotImplemented	Placeholder during phased implementation.
BackendError	Unclassified StormLib/CascLib failure; see nativeError.
ChunkTruncated	A chunk header or payload overruns the file buffer.
ChunkSizeMismatch	A chunk's size disagrees with its binary struct layout.
ChunkMissing	A chunk the format requires is absent from the file.
OffsetOutOfBounds	An offset array (M2Array) points outside its base buffer.
InvalidEntityState	An entity's members disagree (e.g. a stored count vs baked satellites).
FormatVersionMismatch	The file's version chunk disagrees with the requested version.
UnsupportedClientVersion	No format instantiation exists for the requested client version.
TableTruncated	A client-database header, record block or satellite block overruns the file.
TableMagicUnknown	A client-database magic wowlib does not support for the requested version.
SchemaMismatch	A client-database record layout disagrees with the generated WoWDBDefs schema.
SchemaBlobInvalid	A WDBS schema blob (or WoWDBDefs source) is malformed or truncated.
TableUnknown	The schema catalog knows no table of the requested name.

Definition at line 18 of file error.hpp.

Expansion

enum class wowlib::Expansion

strong

Enumerator
Vanilla
Tbc
Wotlk
Cata
Mop
Wod
Legion
Bfa
Shadowlands
Dragonflight
TheWarWithin

Definition at line 17 of file expansion.hpp.

Locale

enum class wowlib::Locale

strong

Enumerator
enUS
enGB
deDE
frFR
ruRU
esES
esMX
koKR
zhCN
zhTW
ptBR
itIT

Definition at line 280 of file client_version.hpp.

StorageKind

enum class wowlib::StorageKind

strong

Enumerator
Mpq	Pre-WoD retail clients (< 6.0), StormLib.
Casc	WoD+ retail and all Classic clients, CascLib.

Definition at line 20 of file client_version.hpp.

Function Documentation

cascLocaleFlag()

std::uint32_t wowlib::cascLocaleFlag

(

Locale

locale

)

The CASC_LOCALE_* bit of locale for CascOpenStorage/CascOpenFile locale masks.

Values mirror CascLib's CascPort.h so public headers stay CascLib-free.

Parameters

locale

the locale.

Returns

a single-bit mask value.

Definition at line 79 of file client_version.cpp.

Referenced by wowlib::fs::CascStorage::exists(), and wowlib::fs::CascStorage::readFile().

enumName()

template<typename E>
requires std::is_enum_v<E>

std::string_view wowlib::enumName ( E value )

constexpr

The enumerator name of value, straight from reflection — no handwritten stringification tables anywhere in wowlib.

Template Parameters

E	any enum type.

Parameters

value

the enumerator.

Returns

the identifier, or "<unknown>" for values outside the enumeration. Static storage, constexpr-usable.

Definition at line 19 of file reflect.hpp.

Referenced by operator<<(), wowlib::formats::rangeSuffix(), and to_string().

expansionOf()

std::optional< Expansion > wowlib::expansionOf ( ClientVersion version )

constexpr

Returns

the expansion, or None for unknown majors

Parameters

version

a full client version

Definition at line 71 of file expansion.hpp.

References wowlib::detail::ExpansionVersions, and wowlib::ClientVersion::major.

localeCode()

std::string_view wowlib::localeCode

(

Locale

locale

)

The four-letter code of locale ("enUS", ...) as used in MPQ locale directory and archive names.

Parameters

locale

the locale.

Returns

a static string, never dangling.

Definition at line 55 of file client_version.cpp.

Referenced by wowlib::fs::detail::expandChain(), and wowlib::db::LocString< 8 >::set().

localeFromCode()

std::optional< Locale > wowlib::localeFromCode

(

std::string_view

code

)

Parse a four-letter locale code.

Parameters

code	e.g. "enUS" (case-sensitive, client spelling).

Returns

the locale, or nullopt if the code is unknown.

Definition at line 59 of file client_version.cpp.

References deDE, enGB, enUS, esES, esMX, frFR, itIT, koKR, ptBR, ruRU, zhCN, and zhTW.

makeError()

std::unexpected< Error > wowlib::makeError ( ErrorCode code, std::string message, std::uint32_t nativeError = 0 )

inline

Shorthand for constructing the error branch of a Result.

Parameters

code	the failure category.
message	human-readable context.
nativeError	raw native library error value, if any.

Returns

an unexpected convertible to any Result<T>.

Definition at line 107 of file error.hpp.

Referenced by wowlib::formats::m2::M2OffsetBlock< Derived >::_offsetError(), wowlib::fs::CascStorage::addEncryptionKey(), wowlib::fs::FileSystem::addEncryptionKey(), wowlib::fs::ClientFileSystem< MpqStorage, NullListfile >::addFile(), wowlib::formats::wmo::group::detail::WMOGroupBody< canonicalVersion(V, WmoGroupPivots, WmoVersions)>::appendTexcoordSet(), wowlib::formats::wmo::group::detail::WMOGroupBody< canonicalVersion(V, WmoGroupPivots, WmoVersions)>::appendVertexColorLayer(), wowlib::formats::detail::chunkError(), wowlib::db::DynTable::columnIndex(), wowlib::db::DynTable::columnInfo(), wowlib::formats::blp::BLP::decode(), wowlib::formats::blp::detail::DxtCodec::decode(), wowlib::fs::ClientInstall::detect(), wowlib::formats::blp::BLP::encode(), wowlib::formats::blp::detail::DxtCodec::encode(), wowlib::fs::CascStorage::enumerateFdids(), wowlib::fs::MpqStorage::enumeratePaths(), wowlib::db::DynTable::eraseRow(), wowlib::db::DynTable::findById(), wowlib::fs::CascStorage::importKeys(), wowlib::fs::FileSystem::importKeys(), wowlib::fs::CsvListfile::load(), wowlib::db::SchemaCatalog::lookup(), wowlib::formats::blp::BLP::mip(), wowlib::fs::detail::FdidAllocator::next(), wowlib::fs::ProjectDirectory::open(), wowlib::db::wdc::WdcImage::parse(), wowlib::formats::adt::detail::ADT< V >::parseFile(), wowlib::formats::wdl::detail::WDL< V >::patchFile(), wowlib::db::DynTable::podColumn(), wowlib::db::TableCore::read(), wowlib::formats::adt::detail::ADT< V >::read(), wowlib::formats::adt::MH2OData::read(), wowlib::formats::blp::BLP::read(), wowlib::formats::m2::detail::M2< V >::read(), wowlib::formats::wdl::detail::WDL< V >::read(), wowlib::formats::wdt::detail::WDT< V >::read(), wowlib::formats::wmo::detail::WMO< V >::read(), wowlib::formats::wmo::detail::WMO< V >::read(), wowlib::formats::wmo::group::chunks::MLIQData::read(), wowlib::fs::ProjectDirectory::read(), wowlib::formats::detail::readEntity(), wowlib::fs::CascStorage::readFile(), wowlib::fs::MpqStorage::readFile(), wowlib::formats::adt::detail::MapChunk< V >::readFrom(), wowlib::db::readWdb2(), wowlib::db::readWdbc(), wowlib::db::wdc::readWdc(), wowlib::fs::CsvListfile::registerPath(), wowlib::fs::NullListfile::registerPath(), wowlib::fs::CsvListfile::save(), wowlib::db::LocString< 8 >::set(), wowlib::formats::blp::BLP::setMip(), wowlib::formats::wmo::group::detail::WMOGroupBody< canonicalVersion(V, WmoGroupPivots, WmoVersions)>::setTexcoordSet(), wowlib::formats::wmo::group::detail::WMOGroupBody< canonicalVersion(V, WmoGroupPivots, WmoVersions)>::setVertexColorLayer(), wowlib::db::TableCore::write(), wowlib::formats::adt::detail::ADT< V >::write(), wowlib::formats::blp::BLP::write(), wowlib::formats::blp::BLP::write(), wowlib::formats::m2::detail::M2< V >::write(), wowlib::formats::m2::detail::Skeleton< V >::write(), wowlib::formats::wdl::detail::WDL< V >::write(), wowlib::formats::wdt::detail::WDT< V >::write(), wowlib::formats::wmo::detail::WMO< V >::write(), wowlib::fs::ProjectDirectory::write(), wowlib::formats::detail::writeEntity(), wowlib::db::writeWdb2(), and wowlib::db::wdc::writeWdc().

normalizePath()

std::string wowlib::normalizePath

(

std::string_view

path

)

Canonicalize a client-internal file path.

Canonical form is lowercase ASCII with backslash separators — the MPQ hashing convention — so every map key and comparison in the library uses one representation. Forward slashes are converted, duplicate separators collapsed, and leading/trailing separators dropped.

Parameters

path	the path in any accepted spelling ("World/Maps/Azeroth.wdt").

Returns

the canonical spelling ("world\\maps\\azeroth.wdt").

Definition at line 4 of file path.cpp.

Referenced by wowlib::fs::CsvListfile::contains(), wowlib::fs::MpqStorage::enumeratePaths(), wowlib::FileKey::FileKey(), wowlib::FileKey::FileKey(), wowlib::fs::CsvListfile::pathToFdid(), wowlib::fs::ProjectDirectory::read(), wowlib::fs::CsvListfile::registerPath(), wowlib::fs::ProjectDirectory::resolve(), wowlib::audit::Auditor::roundtrip(), and wowlib::fs::ProjectDirectory::write().

operator<<()

std::ostream & wowlib::operator<<	(	std::ostream &	out,
		const ClientVersion &	version )

render version as "major.minor.patch.build", with the flavor appended when it is not Retail ("1.15.9.69109 (ClassicEra)") — a Classic version is unreadable without it, since the tuple alone says nothing about the client.

Welded as str / __tostring.

Parameters

out	the stream.
version	the version to render.

Returns

out.

Definition at line 10 of file client_version.cpp.

References wowlib::ClientVersion::build, enumName(), wowlib::ClientVersion::major, wowlib::ClientVersion::minor, and wowlib::ClientVersion::patch.

to_string() [1/2]

std::string wowlib::to_string ( const Error & error )

inline

The human-readable rendering of error: its code spelling, its message, and the native error value when there is one.

Found by ADL, which is what makes it a binding contract and not just a convenience. A rod that maps the error branch of a Result<T> onto its target language's exception channel — welder's C#/.NET rod does exactly that, since .NET has no result type — has to turn an arbitrary E into message text, and looks for an ADL to_string(e) first. Without this the C# bindings fail to build with a diagnostic naming the omission, rather than silently throwing exceptions that carry nothing.

Parameters

error

the failure to render.

Returns

"<Code>: <message>", plus " (native <n>)" when non-zero.

Definition at line 84 of file error.hpp.

References wowlib::Error::code, wowlib::Error::message, wowlib::Error::nativeError, and to_string().

to_string() [2/2]

std::string_view wowlib::to_string ( ErrorCode code )

constexpr

The enumerator spelling of code, obtained via reflection.

Parameters

code	the error code.

Returns

a static string, never dangling.

Definition at line 55 of file error.hpp.

References enumName().

Referenced by to_string().

toClientVersion()

ClientVersion wowlib::toClientVersion ( Expansion expansion )

constexpr

The last-minor-of-major client version wowlib targets for this expansion (the versions constant).

Returns

the matching versions constant

Parameters

expansion

the expansion

Definition at line 56 of file expansion.hpp.

References wowlib::detail::ExpansionVersions.

toExpansion()

std::optional< Expansion > wowlib::toExpansion ( ClientVersion version )

constexpr

The expansion whose targeted release is exactly this version.

Never matches a Classic constant — Classic clients are not expansion releases; pass version.format_lineage to ask which expansion's FORMATS one uses.

Returns

the expansion, or None if the version is not one of the versions constants

Parameters

version

a full client version

Definition at line 64 of file expansion.hpp.

References wowlib::detail::ExpansionVersions.

Referenced by wowlib::formats::rangeSuffix().

toNativeRelative()

std::string wowlib::toNativeRelative

(

std::string_view

canonical

)

Convert a canonical path to a forward-slash relative path for use on the native filesystem (project-directory overlay on POSIX).

Parameters

canonical

a path in canonical form.

Returns

the same path with '/' separators.

Definition at line 23 of file path.cpp.

Referenced by wowlib::fs::CsvListfile::registerPath(), wowlib::fs::CsvListfile::save(), and wowlib::fs::ProjectDirectory::write().