WDL entity¶
A map's low-resolution heightmap file as one versioned entity. It is
version-parametric: the layout differs by client version, which wowlib models
as one WDL<version> per expansion (Python: WDLVanilla,
WDLTbcToWod, WDLLegion, WDLBfa, …). This page documents the generic
model, shown as WDL⟨version⟩.
Each field carries its chunk FourCC (linking to wowdev.wiki). A field whose availability is version-restricted also carries an expansion badge (both ends inclusive); a field with no badge exists in every supported version. The badges are generated from the C++ sources, so they cannot drift.
Reading speaks buffers or the filesystem gateway (read(data) /
read(fs, key)); writing returns bytes or stores through the project overlay
(write() / write(fs, key)). An entity read from a client file rewrites
byte-for-byte until modified; once tiles are added or removed, the write
rebuilds the stream — every non-tile chunk in canonical order, then each
tile's chunks interleaved — and restamps the MAOF offsets from the finished
layout.
The WDL base¶
Bases: FileEntity
A map's low-resolution heightmap file, abstract over the client version — the background mountain silhouettes. Construct the concrete version with WDL.for_version(expansion), then read()/write(); the per-version WDL* classes are subclasses. See https://wowdev.wiki/WDL.
convert(target: Literal[Vanilla]) -> WDL⟨version⟩
convert(target: Literal[Tbc]) -> WDL⟨version⟩
convert(target: Literal[Wotlk]) -> WDL⟨version⟩
convert(target: Literal[Cata]) -> WDL⟨version⟩
convert(target: Literal[Mop]) -> WDL⟨version⟩
convert(target: Literal[Wod]) -> WDL⟨version⟩
convert(target: Literal[Legion]) -> WDL⟨version⟩
convert(target: Literal[Bfa]) -> WDL⟨version⟩
convert(target: Literal[Shadowlands]) -> WDL⟨version⟩
convert(target: Literal[Dragonflight]) -> WDL⟨version⟩
convert(target: Literal[TheWarWithin]) -> WDL⟨version⟩
convert(target: Expansion) -> AnyWDL
Rebuild this heightmap 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.
staticmethod¶
for_version(expansion: Expansion) -> WDL⟨version⟩Construct the concrete WDL for a client version — the abstract WDL is never instantiated directly. The return type narrows per expansion (a typed overload per Expansion member), so for_version(Expansion.Wotlk) returns a WDLWotlk; a runtime Expansion value yields the AnyWDL union.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
Literal[Vanilla]
|
the expansion to convert to |
required |
Returns:
| Type | Description |
|---|---|
WDL⟨version⟩
|
the converted heightmap; raises when a ladder step is not implemented |
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 |
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 |
Fields¶
Header¶
The file version.
property
writable
¶
The WDL format version; 18 for every supported client.
Object placements¶
The low-resolution model silhouettes: WMO names and placements up to WoD, the MLDD/MLMD FileDataID placements since Legion.
property
¶
One byte per WMO placement (MLMB, BfA; same count and order as lod_map_objects — the ADT twin pairs with MODF in _obj0 and MLMD in _obj1). Semantics unknown; the 8.3.7 fleet survey (1300+ instances) shows an enum-like value set (0x19/0x20/0x26/0x33/0x40/0x46/ 0x80) that clusters per map, varies per instance of the same asset, and does not correlate with the placement radius; 0x80 co-occurs with other values on the same asset like an override state.
property
¶
MLDL (9.x+): per-lod_doodads values, engaged by placement flag 0x8 (as the ADT chunk of the same name).
Tile table¶
The 64 x 64 tile offset table and the per-tile heightmap, hole-mask and ocean-mask chunks it addresses.
property
¶
holes: list[TileHoles]
Per-tile hole masks (MAHO, TBC+): the i-th mask belongs to the i-th heightmap. Blizzard writes one per tile even when all zero; hole masks are all-or-nothing — leave the list empty or give every heightmap its mask. (wowdev.wiki dates MAHO to WotLK, but vanilla WDLs carry none and every 2.4.3 WDL pairs one MAHO per MARE — so it debuts in TBC.)
property
¶
heightmaps: list[TileHeights]
The per-tile heightmaps (MARE), one per nonzero tileOffsets slot, in row-major slot order.