ADT entity

The ADT tile class — the 256 terrain chunks plus the tile-wide texture, model and placement tables, unified across the split ADT files the tile is stored in. Like the other versioned formats, every field below documents once, badged with the chunk it serializes to and the expansion range it exists in (a badge-less field is present in every supported version).

Expansions:VanillaTBCWotLKCataMoPWoDLegionBfASLDFTWW

The ADT tile

ADT

ADT()

Bases: FileEntity

A terrain map tile, abstract over the client version — the .adt file (and, since Cataclysm, its _tex0/_obj0/_obj1/_lod split files) as one entity. Construct the concrete version with ADT.for_version(expansion), then read()/write(); the per-version ADT* classes are subclasses. See https://wowdev.wiki/ADT/v18.

read

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

Load the tile — every split file present — from a client filesystem, replacing this entity's contents. The alpha-map bit depth is supplied by the caller (wowlib does not open the WDT for you).

for_version staticmethod

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

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

Parameters:

Name	Type	Description	Default
source	FileSystem	the filesystem gateway	required
key	FileKey	the tile identity (root .adt path and/or FileDataID)	required
alpha	AlphaFormat	the on-disk alpha-map bit depth for this tile's map (from its WDT MPHD flags)	required

Returns:

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

write

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

Serialize the tile (and, Cata+, every split file) through the filesystem's project overlay; the split-file names derive from the key, which must resolve to a path.

Parameters:

Name	Type	Description	Default
dest	FileSystem	the filesystem gateway	required
key	FileKey	the tile identity; must resolve to a path	required
alpha	AlphaFormat	the on-disk alpha-map bit depth to encode	required

Returns:

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

convert

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

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

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

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

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

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

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

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

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

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

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

convert(target: Expansion) -> AnyADT

Rebuild this tile 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
ADT⟨version⟩	the converted tile; 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

Fields

Header & serialization

The format version, the MHDR header and how this tile's alpha maps were encoded on disk (offsets are re-derived on write).

mver property writable MVER

mver: int

The ADT format version (MVER); 18 for every supported client.

header property writable MHDR

header: MHDRData

The tile header (MHDR): flags; the chunk offsets are derived.

alpha_format property writable

alpha_format: AlphaFormat

How this tile's alpha maps were laid out on disk, recorded from the AlphaFormat passed to read(); write() takes its own explicit argument. wowlib always presents decoded 64x64 maps.

Terrain & water

The 256 terrain chunks and the tile-wide water and flying bounds.

flying_bounds property writable MFBOTBC

flying_bounds: MFBOPlanes

The flying bounds (MFBO, BC+); engaged by the header has_mfbo flag.

water property writable MH2OWotLK

water: MH2OData

The tile's water (MH2O, WotLK+): one liquid entry per chunk.

chunks property MCNK

chunks: list[MapChunk⟨version⟩]

The 256 terrain chunks (MCNK), row-major (index = y * 16 + x).

Textures

The tileset texture table the chunk layers index — filenames pre-8.1, _s.blp/_h.blp FileDataID pairs on 8.1+ height-texturing maps — plus the per-texture parameter tables.

texture_flags property MTXFWotLK

texture_flags: list[SMTextureFlags]

Per-texture flags (MTXF, WotLK+): one entry per MTEX texture.

mamp property writable MAMPCata

mamp: int

The MAMP alpha-map downscale value (Cata+): overrides the MHDR inline value; alpha texture size is 64 / (2^value).

uses_texture_fdids property writable Cata

uses_texture_fdids: bool

Whether this tile stores its textures as MDID/MHID FileDataIDs (8.1+ height-texturing maps) rather than MTEX names; set from the chunk present on read and honored on write.

texture_params property MTXPMoP

texture_params: list[SMTextureParams]

Height-blend texture parameters (MTXP, MoP+): one per texture.

diffuse_texture_ids property MDIDBfA 8.1

diffuse_texture_ids: list[int]

Diffuse-texture FileDataIDs (MDID, 8.1+): the _s.blp tileset textures MapChunk layers index, in place of MTEX names.

height_texture_ids property MHIDBfA 8.1

height_texture_ids: list[int]

Height-texture FileDataIDs (MHID, 8.1+): the _h.blp map paired with each diffuse texture (0 for none).

textures property MTEX

textures: StringBlock

The tileset texture filenames (MTEX): the paths MapChunk layers index. Present unless the tile uses MDID/MHID FileDataIDs (8.1+ height-texturing maps).

Models & placements

The M2/WMO filename tables and the doodad/WMO placements chunks reference into.

model_filenames property MMDX

model_filenames: StringBlock

The M2 model filenames (MMDX) placements reference by MMID index.

model_name_offsets property MMID

model_name_offsets: list[int]

Byte offsets into model_filenames (MMID): a doodad placement's name_id indexes this list.

wmo_filenames property MWMO

wmo_filenames: StringBlock

The WMO filenames (MWMO) placements reference by MWID index.

wmo_name_offsets property MWID

wmo_name_offsets: list[int]

Byte offsets into wmo_filenames (MWID): a WMO placement's name_id indexes this list.

doodad_placements property MDDF

doodad_placements: list[SMDoodadDef]

Doodad (M2) placements on this tile (MDDF).

wmo_placements property MODF

wmo_placements: list[SMMapObjDef]

WMO placements on this tile (MODF).

Structured liquid

Water is decoded to an editable form: MH2OData holds one MapChunkLiquid per terrain chunk, each a stack of LiquidInstance layers with their heightmap, depth, texture-coordinate and per-tile "exists" data (the wire offsets are re-derived on write). MCLQData is the legacy per-chunk liquid (up to and including WotLK — Outland tiles still use it).

MH2OData [water]MH2O

MH2OData()

MH2OData(cells: list[MapChunkLiquid])

The tile's liquid (MH2O, WotLK+): one MapChunkLiquid per terrain cell, in the 16x16 row-major cell order. Decoded from the chunk's offset structure and re-laid on write (the binary offsets are derived). Index it by cell = y * 16 + x.

cells property

cells: list[MapChunkLiquid]

Liquid for each of the 256 terrain chunks (y * 16 + x).

empty property

empty: bool

Whether the tile has no liquid at all.

MapChunkLiquid

MapChunkLiquid()

MapChunkLiquid(fishable: int, deep: int, has_attributes: bool, instances: list[LiquidInstance])

The liquid of one terrain cell (an MH2O chunk entry): the 8x8 fishable and deep attribute bit masks and the stacked liquid layers (instances). A cell with no liquid has no instances.

fishable property writable

fishable: Annotated[int, uint64]

The 8x8 fishable bit mask (visibility); 0 when the cell omits attributes.

deep property writable

deep: Annotated[int, uint64]

The 8x8 deep bit mask (fatigue water); 0 when the cell omits attributes.

has_attributes property writable

has_attributes: bool

Whether this cell wrote an explicit attributes block (so an all-zero mask round-trips as present rather than omitted).

instances property

instances: list[LiquidInstance]

The stacked liquid layers over this chunk.

empty property

empty: bool

Whether the chunk carries any liquid.

LiquidInstance

LiquidInstance()

LiquidInstance(liquid_type: int, liquid_object_or_lvf: int, vertex_format: LiquidVertexFormat, min_height: float, max_height: float, x_offset: int, y_offset: int, width: int, height: int, exists_bitmap: list[int], heightmap: list[float], depthmap: list[int], uvmap: list[UVMapEntry])

One liquid layer over a terrain cell (an MH2O instance), decoded. The heightmap/depthmap/uvmap arrays are present according to vertex_format and each hold (width + 1) x (height + 1) entries; exists_bitmap (when not empty) is a width x height bit grid selecting which tiles render. Heights outside [min_height, max_height] and the binary offsets are derived, not stored.

liquid_type property writable

liquid_type: int

The liquid type (a LiquidType foreign key: 1 ocean, 2 ocean-flat, 3 slime, 5/6 magma, …).

liquid_object_or_lvf property writable

liquid_object_or_lvf: int

The stored liquid_object_or_lvf field: a LiquidObject id (>= 42) or a raw LiquidVertexFormat; vertex_format holds the resolved layout.

vertex_format property writable

vertex_format: LiquidVertexFormat

The resolved vertex layout wowlib decoded (and will re-lay).

min_height property writable

min_height: float

Minimum surface height (the flat height when no heightmap).

max_height property writable

max_height: float

Maximum surface height.

x_offset property writable

x_offset: int

The liquid rectangle's x offset within the cell (0-7).

y_offset property writable

y_offset: int

The liquid rectangle's y offset within the cell (0-7).

width property writable

width: Annotated[int, uint8]

The liquid rectangle width in tiles (1-8).

height property writable

height: Annotated[int, uint8]

The liquid rectangle height in tiles (1-8).

exists_bitmap property

exists_bitmap: list[int]

The per-tile exists mask, width x height bits row-major (LSB first); empty means every tile renders.

heightmap property

heightmap: list[float]

Surface heights, (width+1) x (height+1) row-major; present for vertex formats height_depth, height_uv, height_uv_depth.

depthmap property

depthmap: list[Annotated[int, uint8]]

Depth bytes, (width+1) x (height+1) row-major; present for height_depth, depth_only, height_uv_depth.

uvmap property

uvmap: list[UVMapEntry]

UV texture coordinates, (width+1) x (height+1) row-major; present for height_uv and height_uv_depth.

vertex_count

vertex_count() -> int

MCLQData

MCLQData()

MCLQData(height_range: CRange, vertices: list[SLVert], tiles: list[int], flows: list[SWFlowv])

A terrain chunk's legacy liquid (MCLQ, up to WotLK, deprecated by MH2O): a 9x9 grid of liquid vertices (SLVert; read as magma/slime via as_magma()), an 8x8 grid of tile flag bytes and the active flow vectors. The height range and the flow-vector count are stored; the trailing pair of flow vectors is always written.

height_range property writable

height_range: CRange

The surface height range (CRange: min, max).

vertices property

vertices: list[SLVert]

The 9x9 = 81 liquid vertices, row-major.

tiles property

tiles: list[Annotated[int, uint8]]

The 8x8 = 64 tile flag bytes (bits: liquid type, don't-render, fatigue).

flows property

flows: list[SWFlowv]

The active flow vectors (0-2).

empty property

empty: bool

Whether the chunk carries no legacy liquid.