DMM — Map Processing and Manipulation

class DMM

The DMM class provides an extensive API for reading and modifying BYOND map files.

DMM instances are created with the following methods:

static from_file(filename: str | os.PathLike[str])

Read the map file from the filename referring to a “.dmm” file.

Once instantiated, the following properties and methods are available:

property filepath: pathlib.Path

A Pathlib path pointing to the DMM’s original filename.

property size: Coord3

The maximum size of the map’s dimensions, i.e. width, length, and height.

tiledef(x: int, y: int, z: int) → Tile

Returns the Tile at the given coordinates.

save_to(filename: str | os.PathLike[str])

Save the map into the file filename.

coords()

Return an iterator over all possible 3D coordinates.

tiles()

Return an iterator over all unique Tiles on the map.

class Tile

Tile objects returned from DMM.tiledef() can be read and operated upon with the following methods.

property area_path: Path

Returns the tile’s area. It is expected that only one /area is present on a tile.

property turf_path: Path

Returns the tile’s turf. It is expected that only one /turf is present on a tile.

convert() → list[dict]

Returns a Python representation of all tile prefabs.

find(prefix: str, exact=False) → list[int]

Returns the indexes of all the prefabs on the tile with the given prefix. If exact is True, then the prefab path must match exactly.

only(prefix: str, exact=False) → int | None

Returns the index of the only prefab with the given prefix, or None if no such prefab exists. Raises an error if there is more than one prefab with the given prefix. If exact is True, then the prefab path must match exactly.

Once the indexes of the prefabs you wish to work with are returned from Tile.find() or Tile.only(), they may be used to operate on the prefabs of the tile with the following methods.

Prefabs

Every Tile is made up of an ordered list of prefabs. Each prefab corresponds to an atom on that tile’s definition, and has a path and optional set of varedits.

Avulto attempts to represent variable edit values with native Python values whenever possible. When a varedit is a type path, it is represented with a Path. When a varedit is a list, it is represented as Dmlist.

Prefabs are always accessed via their index, which can be retrieved with Tile.find() or Tile.only().

Reading Prefab Data

prefab_path(index: int) → Path

Returns the path of the prefab at index.

prefab_vars(index: int) → list[str]

Returns the list of var names for the varedits at index.

prefab_var(index: int, name: str)

Returns a Python representation of the value of the var name at index.

Raises:

KeyError if the var name has not been edited at index.

get_prefab_var(index: int, name: str, default: any)

Returns a Python representation of the value of the var name at prefab index. If the var name has not been edited, returns default.

Modifying Prefab Data

set_prefab_var(index: int, name: str, val)

Sets the value of the var name at index to val.

set_path(index: int, path: Path | str)

Sets the path of the prefab at index to path, preserving any varedits.

add_path(index: int, path: Path | str)

Adds a prefab with the given path at index index.

del_prefab(index: int)

Deletes the prefab at index.

del_prefab_var(index: int, name: str)

Deletes the varedit of the var name from the prefab at index.