WMO entity

The user-facing compound WMO — the assembly with everything baked in: the root file plus every group file, read and written as one object. WMO is the abstract base; each expansion has a concrete subclass (WMOWotlk, WMOShadowlands, …) exposing that version's layout. Construct a concrete version with for_version(expansion); read/write speak the filesystem gateway (or plain buffers, with the group files passed alongside).

The root file (WMORoot) and the group files (WMOGroup) are the assembly's two halves; their field-by-field references, with expansion and FourCC badges, live on WMO root and WMO group.

The WMO assembly

WMO

WMO()

Bases: FileEntity

A whole world map object, abstract over the client version — the root file and all its group files as one entity. Construct the concrete version with WMO.for_version(expansion), then read()/write(); the per-version WMO* classes are subclasses. See https://wowdev.wiki/WMO.

read

read(source: FileSystem, key: FileKey) -> None

read(source: Buffer | BinaryIO, groups: Sequence[Buffer | BinaryIO]) -> None

Load the assembly — the root file and every numbered group file — from a client filesystem, replacing this entity's contents.

for_version staticmethod

for_version(expansion: Expansion) -> WMO⟨version⟩

Construct the concrete WMO for a client version — the abstract WMO is never instantiated directly. The return type narrows per expansion (a typed overload per Expansion member), so for_version(Expansion.Wotlk) returns a WMOWotlk; a runtime Expansion value yields the AnyWMO union.

Parameters:

Name	Type	Description	Default
source	FileSystem	the filesystem gateway	required
key	FileKey	the root file identity; the "_000" … group keys derive from it	required

Returns:

Type	Description
None	nothing; raises on a missing file or malformed chunk stream

Parse the assembly from memory: the root image plus one buffer (or binary file-like) per group file, in group order.

Parameters:

Name	Type	Description	Default
source	Buffer | BinaryIO	the root file bytes	required
groups	Sequence[Buffer | BinaryIO]	every group file's bytes, ordered	required

Returns:

Type	Description
None	nothing; raises on a malformed chunk stream

write

write(dest: FileSystem, key: FileKey) -> None

write(dest: BinaryIO, groups: Sequence[BinaryIO]) -> None

Serialize the root and every group file through the filesystem's project overlay.

Parameters:

Name	Type	Description	Default
dest	FileSystem	the filesystem gateway	required
key	FileKey	the root file identity; must resolve to a path, from which the group file names derive	required

Returns:

Type	Description
None	nothing; raises when the key has no path or a file fails to write

Serialize into binary sinks: the root into dest, each group into its own sink — exactly one per group, in group order.

Parameters:

Name	Type	Description	Default
dest	BinaryIO	where the root file bytes are written	required
groups	Sequence[BinaryIO]	one binary sink per group file, ordered	required

Returns:

Type	Description
None	nothing; raises when the sink count mismatches the group count

convert

convert(target: Literal[Vanilla]) -> WMO⟨version⟩

convert(target: Literal[Tbc]) -> WMO⟨version⟩

convert(target: Literal[Wotlk]) -> WMO⟨version⟩

convert(target: Literal[Cata]) -> WMO⟨version⟩

convert(target: Literal[Mop]) -> WMO⟨version⟩

convert(target: Literal[Wod]) -> WMO⟨version⟩

convert(target: Literal[Legion]) -> WMO⟨version⟩

convert(target: Literal[Bfa]) -> WMO⟨version⟩

convert(target: Literal[Shadowlands]) -> WMO⟨version⟩

convert(target: Literal[Dragonflight]) -> WMO⟨version⟩

convert(target: Literal[TheWarWithin]) -> WMO⟨version⟩

convert(target: Expansion) -> AnyWMO

Rebuild this assembly as the target expansion's concrete class, stepping the version ladder one adjacent release at a time (this instance is left unchanged). The return type narrows when the target is a literal.

Parameters:

Name	Type	Description	Default
target	Literal[Vanilla]	the expansion to convert to	required

Returns:

Type	Description
WMO⟨version⟩	the converted assembly; raises when a ladder step is not implemented

validate

validate() -> ValidationReport

Check the logical integrity contracts this file must satisfy to LOAD in the client, which write() deliberately never enforces. Call it before writing when you want to know the result will load. A file read from a client and left unmodified reports no errors; warnings mark states real client files ship.

Returns:

Type	Description
ValidationReport	every violated contract, each with its member path

ensure_valid

ensure_valid() -> None

Validate and raise on the first error instead of returning a report — the assert-style face of validate().

Returns:

Type	Description
None	nothing; raises when validate() finds any error

WMO⟨version⟩

WMO⟨version⟩()

Bases: WMO

A whole world map object for one client version: the root file and all its group files as one entity. Group files are located by GFID (Legion+ clients) or the "{root}_NNN.wmo" naming convention. An entity read from a client and left unmodified rewrites byte-for-byte. See https://wowdev.wiki/WMO.

root property writable

root: WMORoot⟨version⟩

The root file contents.

groups property

groups: list[WMOGroup⟨version⟩]

The group files, in group order.

validate

validate() -> ValidationReport

Check the logical integrity contracts this object must satisfy to LOAD in the client — across the root file AND every group file — which write() deliberately never enforces. Call it before writing when you want to know the files will load. An object read from a client and left unmodified reports no errors; warnings mark states real client files ship.

Returns:

Type	Description
ValidationReport	every violated contract, each with its member path
ValidationReport	("root..." / "groups[i]...")

ensure_valid

ensure_valid() -> None

Validate and raise on the first error instead of returning a report — the assert-style face of validate().

Returns:

Type	Description
None	nothing; raises when validate() finds any error

One layout per expansion, documented generically

The WMO layout is version-parametric — WMO<version> (Python: WMOWotlk, WMOShadowlands, …) per expansion. Every version shares the same field names; a field simply exists only within its expansion range. The WMO root and WMO group pages document that generically rather than repeating a dozen per-version class listings.

See the guide's Reading a WMO for a worked example.