Namespaces
namespace	adt
namespace	blp
namespace	common
namespace	detail
namespace	m2
namespace	wdl
namespace	wdt
namespace	wmo

Classes
struct	Absent
	A distinct empty base per Trait, so an entity inheriting several inactive version slots never inherits the same empty type twice (ill-formed). More...
struct	ChunkBlob
	An unparsed chunk payload, preserved verbatim for round-trip. More...
struct	ChunkedFile
	The serialization face of a chunked entity, mixed in CRTP-style: an entity struct E : ChunkedFile<E> carries the ChunkExtras bookkeeping and gains the read()/write() methods every file representation shares. More...
struct	ChunkExtras
	Round-trip bookkeeping common to every chunked entity: the encounter journal, unmodeled chunks, and stray trailing bytes. More...
struct	FileEntityBase
	The version-agnostic root of every file-level entity (welded as "FileEntity"). More...
struct	JournalEntry
	One chunk encounter in file order — the write path replays the journal to reproduce the original byte layout exactly. More...
struct	RangeRow
	One row of a family's welded range table: the alias suffix (stringized from the x-macro) and the range's canonical version. More...
class	Repeated
	Storage for a chunk that may appear up to N times in one entity (MOTV texcoord sets, MOCV vertex-color layers). More...
class	StringBlock
struct	UnknownChunk
	A chunk the entity does not model, preserved verbatim for round-trip. More...
struct	ValidationIssue
	One validate() finding: where it is, how bad it is, and what is wrong. More...
class	ValidationReport
struct	VersionTag
	Tags the target version in convert_step overload signatures. More...

Concepts
concept	ChunkedEntity
	A type the chunk serializer can read and write: carries the round-trip bookkeeping and knows which client version it is laid out for.
concept	SelfSerializing
	A member type that owns its chunk-payload encoding: the serializer hands it the raw payload on read and the output buffer on write (StringBlock, ChunkBlob).
concept	VersionedEntity
	An entity the walker can gate by client version: anything carrying the static constexpr ClientVersion version every format entity declares (chunked files, M2 offset blocks, ADT tiles and map chunks alike).

Typedefs
template<ClientVersion V, ClientVersion Since, class Trait, ClientVersion Until = VersionNeverRemoved>
using	Slot = std::conditional_t<(V.formatLineage() >= Since && V.formatLineage() < Until), Trait, Absent<Trait>>
	A version-gated base: the entity inherits Trait (flattening its chunk members in) iff Since <= V < Until, else the empty absent<Trait>.

Enumerations
enum class	FourCCEndian : std::uint8_t { Reversed , Forward }
	How a chunk's FourCC characters are laid out on disk. More...
enum class	ValidationSeverity : std::uint8_t { Warning , Error }
	How a validation finding affects the file's fitness for the client. More...

Functions
consteval detail::ChunkSpec	chunk (const char(&cc)[5], FourCCEndian endian=FourCCEndian::Reversed)
	Declare the chunk a member maps to.
consteval detail::SinceSpec	since (ClientVersion v)
	Restrict a member to entity versions >= v (inclusive).
consteval detail::UntilSpec	until (ClientVersion v)
	Restrict a member to entity versions < v (exclusive).
consteval detail::RepeatsSpec	repeats (std::uint32_t max)
	Allow a chunk to appear up to max times (e.g.
consteval detail::GatedBySpec	gatedBy (std::uint32_t mask)
	Make an offset-entity member's binary presence conditional on the entity's globalFlags: it occupies bytes only when globalFlags & mask is non-zero (M2's textureCombinerCombos behind global flag 0x8).
consteval detail::OffsetAfterSpec	offsetAfter (std::string_view name)
	Anchor a version-trait member at its positional layout position: the offset serializer walks the entity's OWN members in declaration order and splices each trait-base member right after the own member named here.
consteval detail::CountMatchesSpec	countMatches (std::string_view name, std::uint32_t scale=1)
	Declare a companion-count contract: when this member is engaged (non-empty), its element count times scale must equal the named sibling member's count.
consteval detail::CountMultipleOfSpec	countMultipleOf (std::uint32_t divisor)
	Declare a granularity contract: the member's element count must be a multiple of divisor (triangle index arrays: 3).
consteval detail::CountExactlySpec	countExactly (std::uint32_t count)
	Declare a fixed-size contract: when engaged, the member holds exactly count elements because the format fixes the grid (an ADT map chunk's 145 height samples, its 4096-byte shadow map).
consteval detail::IndexesSpec	indexes (std::string_view name)
	Declare a referential contract: every element of this (integral) vector member is an index into the named sibling member, so each must be less than the sibling's element count.
consteval detail::IndexesOptionalSpec	indexesOptional (std::string_view name)
	Declare a referential contract that tolerates the "none" sentinel: like indexes, except an element that is negative (signed lookup) or all-ones (an unsigned -1, e.g.
consteval detail::IndexesInRootSpec	indexesInRoot (std::string_view name)
	Declare a cross-entity referential contract: every element of this (integral) vector member is an index into the named member of the ASSEMBLY's root entity (a WMO group's lightRefs into the root's lights).
consteval detail::ExpectedValueSpec	expectedValue (std::uint32_t value)
	Declare an exact-value contract on an integral data member (format version fields: WMO MVER is always 17).
template<typename E> requires std::is_scoped_enum_v<E>
constexpr bool	hasFlag (std::underlying_type_t< E > value, E flag)
	Whether flag bit flag is set in the raw binary value value.
template<typename E> requires std::is_scoped_enum_v<E>
constexpr bool	hasFlag (E value, E flag)
	Whether flag bit flag is set in the enum-typed field value value.
template<typename E> requires std::is_scoped_enum_v<E>
constexpr void	setFlag (E &value, E flag, bool on=true)
	Set (or clear) flag bit flag in the enum-typed field value.
constexpr std::uint32_t	fourcc (const char(&cc)[5], FourCCEndian endian=FourCCEndian::Reversed)
	The host integer a scanned chunk id compares equal to for code cc.
constexpr std::string	fourccToString (std::uint32_t fourcc, FourCCEndian endian=FourCCEndian::Reversed)
	The readable four-character spelling of a scanned chunk id.
constexpr ClientVersion	versionFloor (ClientVersion v, std::span< const ClientVersion > pivots)
	The latest pivot at or below v — the identity of v's range.
constexpr ClientVersion	canonicalVersion (ClientVersion v, std::span< const ClientVersion > pivots, std::span< const ClientVersion > grid)
	The canonical version v collapses to: the FIRST grid version in v's range.
constexpr std::string	rangeSuffix (ClientVersion canonical, std::span< const ClientVersion > pivots, std::span< const ClientVersion > grid)
	The suffix naming canonical's range on grid: the plain expansion name for a single-version range ("Wotlk"), "FirstToLast" for an interior range ("CataToMop"), and "FirstPlus" for a range reaching the grid's end ("LegionPlus") — trailing ranges grow with every new release, and the Plus spelling keeps their name stable when they do.
constexpr bool	rangesValid (std::span< const RangeRow > rows, std::span< const ClientVersion > pivots, std::span< const ClientVersion > grid)
	Does rows exactly enumerate the family's ranges — ascending, one row per distinct canonical of grid, each named exactly as rangeSuffix derives?
template<template< ClientVersion > class E, ClientVersion From, ClientVersion To>
consteval bool	hasConvertPath ()
	Whether every convert_step along the CANONICAL ladder from from to to exists, i.e.
template<ClientVersion To, template< ClientVersion > class E, ClientVersion From> requires (!std::is_same_v< decltype(SupportedVersions<E>), const std::nullptr_t>)
auto	convert (const E< From > &src) -> Result< E< canonicalVersion(To, VersionPivots< E >, SupportedVersions< E >)> >
	Convert src to its to - version representation by composing convert_step overloads along the format's CANONICAL ladder (one step per range boundary crossed; versions inside one range are the same type and cost nothing).

Variables
template<>
constexpr auto	SupportedVersions< adt::ADT > = adt::AdtVersions
	The ADT's supported-version ladder: every targeted last-minor-of-major release, in release order (see adt::AdtVersions).
template<>
constexpr auto	SupportedVersions< adt::detail::ADT > = adt::AdtVersions
	The same ladder keyed on the detail template: convert() DEDUCES the family from an entity reference, and deduction sees adt::detail::ADT (an alias template is not identity-equal to its target for template-template match).
template<>
constexpr auto	VersionPivots< adt::ADT > = adt::AdtPivots
	The assembly's canonicalization pivots (both spellings, as above).
template<>
constexpr auto	VersionPivots< adt::detail::ADT > = adt::AdtPivots
constexpr detail::OptionalSpec	Optional {}
	Mark a chunk member the format does not require: absence on read is fine.
constexpr detail::HeaderSpec	Header {}
	Mark a member as a container payload's raw header prelude (e.g.
constexpr detail::ContainerSpec	Container {}
	Mark a chunk member whose payload is itself a chunk stream (e.g.
constexpr detail::RepeatingSpec	Repeating {}
	Mark a chunk that appears once PER ELEMENT of a std::vector<Element> member, any number of times: each encounter appends one element (whole payload -> element), and each element writes back as its own chunk — unlike a plain vector member, whose single chunk payload is the whole array.
constexpr detail::SequenceDataSpec	SequenceData {}
	Mark an offset-entity member (a nested std::vector<std::vector<T>>, one inner array per animation sequence) whose inner data may live in an external buffer — M2 low-priority sequences store their track data in .anim files.
constexpr detail::NonemptySpec	Nonempty {}
	Declare a presence contract: the member must hold data for the file to be meaningful to the client, even though read() tolerates its absence (a required-content marker for optional-on-read chunks).
constexpr ClientVersion	VersionNeverRemoved {255, 0, 0, 0}
	Above any supported client build — the default Until (never removed).
template<template< ClientVersion > class E>
constexpr auto	SupportedVersions = nullptr
	The ordered release list of format template E.
template<template< ClientVersion > class E>
constexpr auto	VersionPivots = nullptr
	The canonicalization pivots of format template E (the assembly's pivot list from its boundaries header) — convert() walks the CANONICAL ladder these define: versions inside one range are the same type and need no step.
template<>
constexpr auto	SupportedVersions< m2::M2 > = m2::M2Versions
	The M2's supported-version ladder: every targeted last-minor-of-major release, in release order (see m2::M2Versions).
template<>
constexpr auto	SupportedVersions< m2::detail::M2 > = m2::M2Versions
	The same ladder keyed on the detail template (see the WMO counterpart: deduction from an entity reference sees m2::detail::M2).
template<>
constexpr auto	VersionPivots< m2::M2 > = m2::M2AssemblyPivots
	The assembly's canonicalization pivots (both spellings, as above).
template<>
constexpr auto	VersionPivots< m2::detail::M2 > = m2::M2AssemblyPivots
template<>
constexpr auto	SupportedVersions< wdl::WDL > = wdl::WdlVersions
	The WDL's supported-version ladder: every targeted last-minor-of-major release, in release order (see wdl::WdlVersions).
template<>
constexpr auto	SupportedVersions< wdl::detail::WDL > = wdl::WdlVersions
	The same ladder keyed on the detail template: convert() DEDUCES the family from an entity reference, and deduction sees wdl::detail::WDL — an alias template is not identity-equal to its target for template-template matching.
template<>
constexpr auto	VersionPivots< wdl::WDL > = wdl::WdlPivots
	The entity's canonicalization pivots (both spellings, as above).
template<>
constexpr auto	VersionPivots< wdl::detail::WDL > = wdl::WdlPivots
template<>
constexpr auto	SupportedVersions< wdt::WDT > = wdt::WdtVersions
	The WDT's supported-version ladder: every targeted last-minor-of-major release, in release order (see wdt::WdtVersions).
template<>
constexpr auto	SupportedVersions< wdt::detail::WDT > = wdt::WdtVersions
	The same ladder keyed on the detail template: convert() DEDUCES the family from an entity reference, and deduction sees wdt::detail::WDT — an alias template is not identity-equal to its target for template-template matching.
template<>
constexpr auto	VersionPivots< wdt::WDT > = wdt::WdtAssemblyPivots
	The assembly's canonicalization pivots (both spellings, as above).
template<>
constexpr auto	VersionPivots< wdt::detail::WDT > = wdt::WdtAssemblyPivots
template<>
constexpr auto	SupportedVersions< wmo::WMO > = wmo::WmoVersions
	The WMO's supported-version ladder: every targeted last-minor-of-major release, in release order (see wmo::WmoVersions).
template<>
constexpr auto	SupportedVersions< wmo::detail::WMO > = wmo::WmoVersions
	The same ladder keyed on the detail template: convert() DEDUCES the family from an entity reference, and deduction sees wmo::detail::WMO — an alias template is not identity-equal to its target for template-template matching.
template<>
constexpr auto	VersionPivots< wmo::WMO > = wmo::WmoAssemblyPivots
	The assembly's canonicalization pivots (both spellings, as above).
template<>
constexpr auto	VersionPivots< wmo::detail::WMO > = wmo::WmoAssemblyPivots

Typedef Documentation

◆ Slot

template<ClientVersion V, ClientVersion Since, class Trait, ClientVersion Until = VersionNeverRemoved>

using wowlib::formats::Slot = std::conditional_t<(V.formatLineage() >= Since && V.formatLineage() < Until), Trait, Absent<Trait>>

A version-gated base: the entity inherits Trait (flattening its chunk members in) iff Since <= V < Until, else the empty absent<Trait>.

Group the chunks that share an availability range into one Trait; a chunk removed at some version goes in a trait with that version as Until.

V is compared on the retail timeline (ClientVersion::formatLineage), so a Classic version gets the chunk set its ENGINE defines rather than the one its legacy version number suggests. Entities reached through the canonicalizing family aliases are already instantiated at a retail grid version, so this only matters to code naming a detail:: template itself.

Definition at line 41 of file version_slot.hpp.

Enumeration Type Documentation

◆ FourCCEndian

enum class wowlib::formats::FourCCEndian : std::uint8_t

strong

How a chunk's FourCC characters are laid out on disk.

Enumerator

Reversed

The characters are stored reversed: 'MVER' appears in the file as the bytes "REVM".

The common case — WMO, ADT, WDT, WDL and the M2 wrapper magic all use it.

Forward

The characters are stored as written: 'AFID' appears in the file as the bytes "AFID".

Used by the Legion+ M2 companion chunk ids.

Definition at line 14 of file fourcc.hpp.

◆ ValidationSeverity

enum class wowlib::formats::ValidationSeverity : std::uint8_t

strong

How a validation finding affects the file's fitness for the client.

Enumerator
Warning	Suspicious, but real client files ship it; the file loads.
Error	The client would misread or crash on a file written like this.

Definition at line 39 of file validation.hpp.

Function Documentation

◆ canonicalVersion()

ClientVersion wowlib::formats::canonicalVersion	(	ClientVersion	v,
		std::span< const ClientVersion >	pivots,
		std::span< const ClientVersion >	grid )

constexpr

The canonical version v collapses to: the FIRST grid version in v's range.

Only canonical versions instantiate; every other version aliases to its canonical (the family's welded name covers the range). Classic versions collapse onto the retail grid like any other (see versionFloor), so supporting them costs no extra instantiation.

Parameters

v	the requested version (any flavor).
pivots	the family's change points.
grid	the targeted release list, ascending (WmoVersions / M2Versions or a family's era subset of it).

Returns: the range's first grid version (the grid front when v precedes the whole grid).

Definition at line 69 of file version_range.hpp.

References versionFloor().

Referenced by convert(), hasConvertPath(), wowlib::formats::detail::nextCanonical(), and rangesValid().

◆ chunk()

detail::ChunkSpec wowlib::formats::chunk	(	const char(&)	cc[5],
		FourCCEndian	endian = FourCCEndian::Reversed )

consteval

Declare the chunk a member maps to.

Parameters

cc	the four-character code as on wowdev.wiki, e.g. "MOHD".
endian	disk layout of the code; reversed for all pre-Legion-M2 formats.

Returns: the annotation payload.

Definition at line 174 of file annotations.hpp.

References fourcc(), and Reversed.

Referenced by wowlib::formats::adt::detail::ADT< V >::validate().

◆ convert()

template<ClientVersion To, template< ClientVersion > class E, ClientVersion From>
requires (!std::is_same_v< decltype(SupportedVersions<E>), const std::nullptr_t>)

auto wowlib::formats::convert ( const E< From > & src ) -> Result< E< canonicalVersion(To, VersionPivots< E >, SupportedVersions< E >)> >

Convert src to its to - version representation by composing convert_step overloads along the format's CANONICAL ladder (one step per range boundary crossed; versions inside one range are the same type and cost nothing).

Template Parameters

to	the target client version (a SupportedVersions entry).

Parameters

src	the source entity (a canonical instantiation — every entity built through the public aliases is one).

Returns: the converted entity, or the first failing step's error.

Definition at line 120 of file convert.hpp.

References canonicalVersion(), convert(), wowlib::formats::detail::indexOf(), wowlib::formats::detail::nextCanonical(), SupportedVersions, and VersionPivots.

Referenced by convert().

◆ countExactly()

detail::CountExactlySpec wowlib::formats::countExactly ( std::uint32_t count )

consteval

Declare a fixed-size contract: when engaged, the member holds exactly count elements because the format fixes the grid (an ADT map chunk's 145 height samples, its 4096-byte shadow map).

Absence stays legal — combine with nonempty when the data is also mandatory.

Parameters

count the required element count.

Definition at line 271 of file annotations.hpp.

◆ countMatches()

detail::CountMatchesSpec wowlib::formats::countMatches	(	std::string_view	name,
		std::uint32_t	scale = 1 )

consteval

Declare a companion-count contract: when this member is engaged (non-empty), its element count times scale must equal the named sibling member's count.

Examples: normals countMatches("vertices") (one normal per vertex); polys countMatches("indices", 3) (one per-triangle record per three indices). On a Repeated<> member the contract applies to every filled slot. The sibling name is checked against the entity's members at compile time.

Parameters

name	the sibling member whose count is the reference.
scale	this member's count is 1/scale of the sibling's.

Definition at line 255 of file annotations.hpp.

◆ countMultipleOf()

detail::CountMultipleOfSpec wowlib::formats::countMultipleOf ( std::uint32_t divisor )

consteval

Declare a granularity contract: the member's element count must be a multiple of divisor (triangle index arrays: 3).

Parameters

divisor the required granularity.

Definition at line 262 of file annotations.hpp.

◆ expectedValue()

detail::ExpectedValueSpec wowlib::formats::expectedValue ( std::uint32_t value )

consteval

Declare an exact-value contract on an integral data member (format version fields: WMO MVER is always 17).

Parameters

value the only valid member value.

Definition at line 308 of file annotations.hpp.

◆ fourcc()

std::uint32_t wowlib::formats::fourcc	(	const char(&)	cc[5],
		FourCCEndian	endian = FourCCEndian::Reversed )

constexpr

The host integer a scanned chunk id compares equal to for code cc.

The chunk scanner memcpy's four disk bytes into a host (little-endian) std::uint32_t and compares against this value directly — no per-chunk byte swapping on either side.

Parameters

cc	the four-character code as written on wowdev.wiki, e.g. "MVER".
endian	how the code is laid out on disk.

Returns: the comparison value.

Definition at line 33 of file fourcc.hpp.

References Reversed.

Referenced by wowlib::formats::m2::AnimBuffers::appendChunkTo(), wowlib::formats::detail::ChunkWriter::beginChunk(), chunk(), wowlib::formats::detail::chunkError(), fourccToString(), wowlib::formats::wdl::detail::WDL< V >::oceanMaskTiles(), wowlib::formats::adt::detail::ADT< V >::parseFile(), wowlib::formats::wmo::root::detail::WMORoot< canonicalVersion(V, WmoRootPivots, WmoVersions)>::patchChunk(), wowlib::formats::wdl::detail::WDL< V >::patchFile(), wowlib::formats::detail::readEntity(), wowlib::formats::adt::detail::MapChunk< V >::readFrom(), wowlib::formats::detail::readValue(), wowlib::formats::wdl::detail::WDL< V >::resequencedJournal(), wowlib::formats::m2::AnimCache::window(), and wowlib::formats::adt::detail::ADT< V >::writeFile().

◆ fourccToString()

std::string wowlib::formats::fourccToString	(	std::uint32_t	fourcc,
		FourCCEndian	endian = FourCCEndian::Reversed )

constexpr

The readable four-character spelling of a scanned chunk id.

Parameters

fourcc	a chunk id as memcpy'd from disk by the scanner.
endian	how the code is laid out on disk.

Returns: e.g. "MVER"; non-printable bytes are kept verbatim.

Definition at line 46 of file fourcc.hpp.

References fourcc(), and Reversed.

Referenced by wowlib::formats::detail::chunkError(), wowlib::audit::detail::firstDivergenceChunked(), wowlib::formats::adt::detail::ADT< V >::parseFile(), wowlib::db::TableCore::read(), wowlib::formats::detail::readEntity(), wowlib::formats::adt::detail::MapChunk< V >::readFrom(), wowlib::audit::detail::tallyUnknown(), and wowlib::formats::detail::writeEntity().

◆ gatedBy()

detail::GatedBySpec wowlib::formats::gatedBy ( std::uint32_t mask )

consteval

Make an offset-entity member's binary presence conditional on the entity's globalFlags: it occupies bytes only when globalFlags & mask is non-zero (M2's textureCombinerCombos behind global flag 0x8).

The flags member must precede it in binary order.

Parameters

mask	the flag bits that engage the member.

Definition at line 227 of file annotations.hpp.

◆ hasConvertPath()

template<template< ClientVersion > class E, ClientVersion From, ClientVersion To>

bool wowlib::formats::hasConvertPath ( )

consteval

Whether every convert_step along the CANONICAL ladder from from to to exists, i.e.

whether convert<to>(E<from>) would compile. Lets callers that dispatch over versions at runtime (the Python factories) degrade a missing ladder to a runtime error instead of tripping convert()'s static_assert.

Template Parameters

E	the format template (alias or detail spelling).
From	the source client version (a SupportedVersions entry).
To	the target client version (a SupportedVersions entry).

Definition at line 95 of file convert.hpp.

References canonicalVersion(), hasConvertPath(), wowlib::formats::detail::indexOf(), wowlib::formats::detail::nextCanonical(), SupportedVersions, and VersionPivots.

Referenced by hasConvertPath().

◆ hasFlag() [1/2]

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

bool wowlib::formats::hasFlag	(	E	value,
		E	flag )

nodiscardconstexpr

Whether flag bit flag is set in the enum-typed field value value.

Template Parameters

E	the scoped flag enum (deduced).

Parameters

value	the field's value (possibly OR-combined, possibly carrying undocumented bits).
flag	the named bit to test.

Returns: true when every bit of flag is set in value.

Definition at line 37 of file flags.hpp.

◆ hasFlag() [2/2]

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

bool wowlib::formats::hasFlag	(	std::underlying_type_t< E >	value,
		E	flag )

nodiscardconstexpr

Whether flag bit flag is set in the raw binary value value.

Template Parameters

E	the scoped flag enum (deduced).

Parameters

value	the binary field's raw integer value.
flag	the named bit to test.

Returns: true when every bit of flag is set in value.

Definition at line 26 of file flags.hpp.

Referenced by wowlib::formats::adt::detail::AlphaCodec::prepare(), wowlib::formats::adt::detail::AlphaCodec::read(), wowlib::formats::adt::detail::MapChunk< V >::readFrom(), wowlib::formats::adt::detail::ADT< V >::validate(), and wowlib::formats::wmo::group::detail::WMOGroupBody< canonicalVersion(V, WmoGroupPivots, WmoVersions)>::validateExtra().

◆ indexes()

detail::IndexesSpec wowlib::formats::indexes ( std::string_view name )

consteval

Declare a referential contract: every element of this (integral) vector member is an index into the named sibling member, so each must be less than the sibling's element count.

The sibling name is checked against the entity's members at compile time.

Parameters

name	the sibling member the elements index.

Definition at line 280 of file annotations.hpp.

◆ indexesInRoot()

detail::IndexesInRootSpec wowlib::formats::indexesInRoot ( std::string_view name )

consteval

Declare a cross-entity referential contract: every element of this (integral) vector member is an index into the named member of the ASSEMBLY's root entity (a WMO group's lightRefs into the root's lights).

The member's own entity validates nothing for it — the assembly's validate() resolves the target and applies the check.

Parameters

name	the root-entity member the elements index.

Definition at line 301 of file annotations.hpp.

◆ indexesOptional()

detail::IndexesOptionalSpec wowlib::formats::indexesOptional ( std::string_view name )

consteval

Declare a referential contract that tolerates the "none" sentinel: like indexes, except an element that is negative (signed lookup) or all-ones (an unsigned -1, e.g.

M2's 0xFFFF) means "no reference" and is skipped. The M2 lookup tables are the motivating case — key bones, replacable textures and transform lookups all leave unused slots at -1.

Parameters

name	the sibling member the elements index.

Definition at line 290 of file annotations.hpp.

◆ offsetAfter()

detail::OffsetAfterSpec wowlib::formats::offsetAfter ( std::string_view name )

consteval

Anchor a version-trait member at its positional layout position: the offset serializer walks the entity's OWN members in declaration order and splices each trait-base member right after the own member named here.

Required on every member an offset entity inherits from a conditionally-inherited trait base — base flattening is by-base, never the interleaved layout order. Note this is about correct positional READING of the flat MD20 layout, not about byte-perfect writes (offset formats have none): a field read at the wrong position misaligns every offset after it.

Parameters

name	the own member this one is laid out after.

Definition at line 240 of file annotations.hpp.

◆ rangeSuffix()

std::string wowlib::formats::rangeSuffix	(	ClientVersion	canonical,
		std::span< const ClientVersion >	pivots,
		std::span< const ClientVersion >	grid )

constexpr

The suffix naming canonical's range on grid: the plain expansion name for a single-version range ("Wotlk"), "FirstToLast" for an interior range ("CataToMop"), and "FirstPlus" for a range reaching the grid's end ("LegionPlus") — trailing ranges grow with every new release, and the Plus spelling keeps their name stable when they do.

Parameters

canonical	a canonical grid version (see canonicalVersion).
pivots	the family's change points.
grid	the targeted release list, ascending.

Returns: the suffix, built from the Expansion enumerator spellings.

Definition at line 87 of file version_range.hpp.

References wowlib::enumName(), wowlib::toExpansion(), and versionFloor().

Referenced by rangesValid().

◆ rangesValid()

bool wowlib::formats::rangesValid	(	std::span< const RangeRow >	rows,
		std::span< const ClientVersion >	pivots,
		std::span< const ClientVersion >	grid )

constexpr

Does rows exactly enumerate the family's ranges — ascending, one row per distinct canonical of grid, each named exactly as rangeSuffix derives?

The static_assert guard every family's range x-macro compiles against: neither a stale row nor a wrong name survives a pivot or grid change.

Parameters

rows	the family's declared rows (see RangeRow).
pivots	the family's change points.
grid	the family's release list, ascending.

Returns: whether the table is exact.

Definition at line 118 of file version_range.hpp.

References canonicalVersion(), and rangeSuffix().

◆ repeats()

detail::RepeatsSpec wowlib::formats::repeats ( std::uint32_t max )

consteval

Allow a chunk to appear up to max times (e.g.

MOTV texcoord sets); the member must be a Repeated<T, max>.

Parameters

max	the maximum occurrence count.

Definition at line 201 of file annotations.hpp.

◆ setFlag()

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

void wowlib::formats::setFlag	(	E &	value,
		E	flag,
		bool	on = true )

constexpr

Set (or clear) flag bit flag in the enum-typed field value.

Template Parameters

E	the scoped flag enum (deduced).

Parameters

value	the field to modify.
flag	the named bit to set or clear.
on	true to set, false to clear.

Definition at line 48 of file flags.hpp.

Referenced by wowlib::formats::adt::chunks::SMChunk::setHolesHighRes().

◆ since()

detail::SinceSpec wowlib::formats::since ( ClientVersion v )

consteval

Restrict a member to entity versions >= v (inclusive).

Parameters

v	the first client version the chunk exists in.

Definition at line 180 of file annotations.hpp.

◆ until()

detail::UntilSpec wowlib::formats::until ( ClientVersion v )

consteval

Restrict a member to entity versions < v (exclusive).

Parameters

v	the first client version the chunk no longer exists in.

Definition at line 184 of file annotations.hpp.

◆ versionFloor()

ClientVersion wowlib::formats::versionFloor	(	ClientVersion	v,
		std::span< const ClientVersion >	pivots )

constexpr

The latest pivot at or below v — the identity of v's range.

Two versions with the same floor have identical family content.

v is placed on the retail timeline first (ClientVersion::formatLineage), because that — not the version tuple — is what a client's file layout follows. Only so does a Classic client land in the right range: Cataclysm Classic 4.4.2 is a War Within-era client, and comparing its 4.4 tuple against the pivots would floor it onto the Cataclysm layouts.

Parameters

v	the version to classify (any flavor).
pivots	the family's change points (any order, all retail).

Returns: the floor pivot, or the zero version below every pivot.

Definition at line 50 of file version_range.hpp.

Referenced by canonicalVersion(), and rangeSuffix().

Variable Documentation

◆ Container

detail::ContainerSpec wowlib::formats::Container {}

inlineconstexpr

Mark a chunk member whose payload is itself a chunk stream (e.g.

MOGP): the member type must be a chunked entity and is read recursively.

Definition at line 196 of file annotations.hpp.

◆ Header

detail::HeaderSpec wowlib::formats::Header {}

inlineconstexpr

Mark a member as a container payload's raw header prelude (e.g.

the MOGP group header): memcpy'd off the payload front before its chunks scan.

Definition at line 192 of file annotations.hpp.

◆ Nonempty

detail::NonemptySpec wowlib::formats::Nonempty {}

inlineconstexpr

Declare a presence contract: the member must hold data for the file to be meaningful to the client, even though read() tolerates its absence (a required-content marker for optional-on-read chunks).

Definition at line 315 of file annotations.hpp.

◆ Optional

detail::OptionalSpec wowlib::formats::Optional {}

inlineconstexpr

Mark a chunk member the format does not require: absence on read is fine.

Unmarked chunk members are required — absence is a ChunkMissing error.

Definition at line 188 of file annotations.hpp.

◆ Repeating

detail::RepeatingSpec wowlib::formats::Repeating {}

inlineconstexpr

Mark a chunk that appears once PER ELEMENT of a std::vector<Element> member, any number of times: each encounter appends one element (whole payload -> element), and each element writes back as its own chunk — unlike a plain vector member, whose single chunk payload is the whole array.

The per-tile WDL chunks (MARE/MAHO) and the repeated _mpv groups (PVMI/PVPD/PVBD) are the motivating cases. Interleaving with other repeating chunks round-trips through the journal; fresh entities emit a member's elements consecutively unless the entity resequences its journal (see writeEntity's resequencedJournal hook).

Definition at line 212 of file annotations.hpp.

◆ SequenceData

detail::SequenceDataSpec wowlib::formats::SequenceData {}

inlineconstexpr

Mark an offset-entity member (a nested std::vector<std::vector<T>>, one inner array per animation sequence) whose inner data may live in an external buffer — M2 low-priority sequences store their track data in .anim files.

The offset I/O contexts resolve each outer element's base span (read) / destination buffer (write); without a context the data is inline in the entity's own buffer.

Definition at line 220 of file annotations.hpp.

◆ SupportedVersions

template<template< ClientVersion > class E>

auto wowlib::formats::SupportedVersions = nullptr

inlineconstexpr

The ordered release list of format template E.

Specialize per format (for BOTH the public alias and the detail template — deduction from an entity reference sees the detail one):

template <> inline constexpr auto SupportedVersions<wmo::WMO> = wmo::WmoVersions;

wowlib::formats::wmo::WmoVersions

constexpr std::array WmoVersions

The versions WMO is instantiated (and welded) for: every targeted last-minor-of-major release,...

Definition boundaries.hpp:44

wowlib::formats::SupportedVersions

constexpr auto SupportedVersions

The ordered release list of format template E.

Definition convert.hpp:43

Definition at line 43 of file convert.hpp.

Referenced by convert(), hasConvertPath(), and wowlib::formats::detail::nextCanonical().

◆ SupportedVersions< adt::ADT >

template<>

auto wowlib::formats::SupportedVersions< adt::ADT > = adt::AdtVersions

inlineconstexpr

The ADT's supported-version ladder: every targeted last-minor-of-major release, in release order (see adt::AdtVersions).

Definition at line 17 of file convert.hpp.

◆ SupportedVersions< adt::detail::ADT >

template<>

auto wowlib::formats::SupportedVersions< adt::detail::ADT > = adt::AdtVersions

inlineconstexpr

The same ladder keyed on the detail template: convert() DEDUCES the family from an entity reference, and deduction sees adt::detail::ADT (an alias template is not identity-equal to its target for template-template match).

Definition at line 22 of file convert.hpp.

◆ SupportedVersions< m2::detail::M2 >

template<>

auto wowlib::formats::SupportedVersions< m2::detail::M2 > = m2::M2Versions

inlineconstexpr

The same ladder keyed on the detail template (see the WMO counterpart: deduction from an entity reference sees m2::detail::M2).

Definition at line 24 of file convert.hpp.

◆ SupportedVersions< m2::M2 >

template<>

auto wowlib::formats::SupportedVersions< m2::M2 > = m2::M2Versions

inlineconstexpr

The M2's supported-version ladder: every targeted last-minor-of-major release, in release order (see m2::M2Versions).

convert<to>() walks this one adjacent step at a time.

Definition at line 20 of file convert.hpp.

◆ SupportedVersions< wdl::detail::WDL >

template<>

auto wowlib::formats::SupportedVersions< wdl::detail::WDL > = wdl::WdlVersions

inlineconstexpr

The same ladder keyed on the detail template: convert() DEDUCES the family from an entity reference, and deduction sees wdl::detail::WDL — an alias template is not identity-equal to its target for template-template matching.

Definition at line 26 of file convert.hpp.

◆ SupportedVersions< wdl::WDL >

template<>

auto wowlib::formats::SupportedVersions< wdl::WDL > = wdl::WdlVersions

inlineconstexpr

The WDL's supported-version ladder: every targeted last-minor-of-major release, in release order (see wdl::WdlVersions).

convert<to>() walks this one adjacent step at a time.

Definition at line 20 of file convert.hpp.

◆ SupportedVersions< wdt::detail::WDT >

template<>

auto wowlib::formats::SupportedVersions< wdt::detail::WDT > = wdt::WdtVersions

inlineconstexpr

The same ladder keyed on the detail template: convert() DEDUCES the family from an entity reference, and deduction sees wdt::detail::WDT — an alias template is not identity-equal to its target for template-template matching.

Definition at line 26 of file convert.hpp.

◆ SupportedVersions< wdt::WDT >

template<>

auto wowlib::formats::SupportedVersions< wdt::WDT > = wdt::WdtVersions

inlineconstexpr

The WDT's supported-version ladder: every targeted last-minor-of-major release, in release order (see wdt::WdtVersions).

convert<to>() walks this one adjacent step at a time.

Definition at line 20 of file convert.hpp.

◆ SupportedVersions< wmo::detail::WMO >

template<>

auto wowlib::formats::SupportedVersions< wmo::detail::WMO > = wmo::WmoVersions

inlineconstexpr

The same ladder keyed on the detail template: convert() DEDUCES the family from an entity reference, and deduction sees wmo::detail::WMO — an alias template is not identity-equal to its target for template-template matching.

Definition at line 26 of file convert.hpp.

◆ SupportedVersions< wmo::WMO >

template<>

auto wowlib::formats::SupportedVersions< wmo::WMO > = wmo::WmoVersions

inlineconstexpr

The WMO's supported-version ladder: every targeted last-minor-of-major release, in release order (see wmo::WmoVersions).

convert<to>() walks this one adjacent step at a time.

Definition at line 20 of file convert.hpp.

◆ VersionNeverRemoved

ClientVersion wowlib::formats::VersionNeverRemoved {255, 0, 0, 0}

inlineconstexpr

Above any supported client build — the default Until (never removed).

Definition at line 28 of file version_slot.hpp.

◆ VersionPivots

template<template< ClientVersion > class E>

auto wowlib::formats::VersionPivots = nullptr

inlineconstexpr

The canonicalization pivots of format template E (the assembly's pivot list from its boundaries header) — convert() walks the CANONICAL ladder these define: versions inside one range are the same type and need no step.

Specialize alongside SupportedVersions, for both alias and detail spellings.

Definition at line 51 of file convert.hpp.

Referenced by convert(), hasConvertPath(), and wowlib::formats::detail::nextCanonical().

◆ VersionPivots< adt::ADT >

template<>

auto wowlib::formats::VersionPivots< adt::ADT > = adt::AdtPivots

inlineconstexpr

The assembly's canonicalization pivots (both spellings, as above).

Definition at line 26 of file convert.hpp.

◆ VersionPivots< adt::detail::ADT >

template<>

auto wowlib::formats::VersionPivots< adt::detail::ADT > = adt::AdtPivots

inlineconstexpr

Definition at line 28 of file convert.hpp.

◆ VersionPivots< m2::detail::M2 >

template<>

auto wowlib::formats::VersionPivots< m2::detail::M2 > = m2::M2AssemblyPivots

inlineconstexpr

Definition at line 30 of file convert.hpp.

◆ VersionPivots< m2::M2 >

template<>

auto wowlib::formats::VersionPivots< m2::M2 > = m2::M2AssemblyPivots

inlineconstexpr

The assembly's canonicalization pivots (both spellings, as above).

Definition at line 28 of file convert.hpp.

◆ VersionPivots< wdl::detail::WDL >

template<>

auto wowlib::formats::VersionPivots< wdl::detail::WDL > = wdl::WdlPivots

inlineconstexpr

Definition at line 32 of file convert.hpp.

◆ VersionPivots< wdl::WDL >

template<>

auto wowlib::formats::VersionPivots< wdl::WDL > = wdl::WdlPivots

inlineconstexpr

The entity's canonicalization pivots (both spellings, as above).

Definition at line 30 of file convert.hpp.

◆ VersionPivots< wdt::detail::WDT >

template<>

auto wowlib::formats::VersionPivots< wdt::detail::WDT > = wdt::WdtAssemblyPivots

inlineconstexpr

Definition at line 32 of file convert.hpp.

◆ VersionPivots< wdt::WDT >

template<>

auto wowlib::formats::VersionPivots< wdt::WDT > = wdt::WdtAssemblyPivots

inlineconstexpr

The assembly's canonicalization pivots (both spellings, as above).

Definition at line 30 of file convert.hpp.

◆ VersionPivots< wmo::detail::WMO >

template<>

auto wowlib::formats::VersionPivots< wmo::detail::WMO > = wmo::WmoAssemblyPivots

inlineconstexpr

Definition at line 32 of file convert.hpp.

◆ VersionPivots< wmo::WMO >

template<>

auto wowlib::formats::VersionPivots< wmo::WMO > = wmo::WmoAssemblyPivots

inlineconstexpr

The assembly's canonicalization pivots (both spellings, as above).

Definition at line 30 of file convert.hpp.

Namespaces

Classes

Concepts

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

◆ Slot

Enumeration Type Documentation

◆ FourCCEndian

◆ ValidationSeverity

Function Documentation

◆ canonicalVersion()

◆ chunk()

◆ convert()

◆ countExactly()

◆ countMatches()

◆ countMultipleOf()

◆ expectedValue()

◆ fourcc()

◆ fourccToString()

◆ gatedBy()

◆ hasConvertPath()

◆ hasFlag() [1/2]

◆ hasFlag() [2/2]

◆ indexes()

◆ indexesInRoot()

◆ indexesOptional()

◆ offsetAfter()

◆ rangeSuffix()

◆ rangesValid()

◆ repeats()

◆ setFlag()

◆ since()

◆ until()

◆ versionFloor()

Variable Documentation

◆ Container

◆ Header

◆ Nonempty

◆ Optional

◆ Repeating

◆ SequenceData

◆ SupportedVersions

◆ SupportedVersions< adt::ADT >

◆ SupportedVersions< adt::detail::ADT >

◆ SupportedVersions< m2::detail::M2 >

◆ SupportedVersions< m2::M2 >

◆ SupportedVersions< wdl::detail::WDL >

◆ SupportedVersions< wdl::WDL >

◆ SupportedVersions< wdt::detail::WDT >

◆ SupportedVersions< wdt::WDT >

◆ SupportedVersions< wmo::detail::WMO >

◆ SupportedVersions< wmo::WMO >

◆ VersionNeverRemoved

◆ VersionPivots

◆ VersionPivots< adt::ADT >

◆ VersionPivots< adt::detail::ADT >

◆ VersionPivots< m2::detail::M2 >

◆ VersionPivots< m2::M2 >

◆ VersionPivots< wdl::detail::WDL >

◆ VersionPivots< wdl::WDL >

◆ VersionPivots< wdt::detail::WDT >

◆ VersionPivots< wdt::WDT >

◆ VersionPivots< wmo::detail::WMO >

◆ VersionPivots< wmo::WMO >