DMM — Map Processing and Manipulation

class avulto.DMM

A DMM file.

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: os.PathLike[str] | str) → DMM

Creates a DMM from the given filename.

Once instantiated, the following properties and methods are available:

property filepath: pathlib.Path

The original filename of the DMM.

property size: Coord3

The number of tiles in each of the map’s three dimensions.

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

Return the tile definition at coords (x, y, z).

save_to(filename: Any) → None

Saves the DMM to the given filename.

coords() → collections.abc.Iterator[tuple[int, int, int]]

Return an iterator over all possible 3D coordinates in the map.

tiles() → collections.abc.Iterator[Tile]

Return an iterator over all unique tiles in the map.

The iterator returns a copy of the keys in the map at the time of the call. If a key is removed from the map while the iterator is active, a KeyError may result.

class avulto.Tile

An individual map tile definition.

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

property area_path: TypePath

Returns the path of the tile’s area. Returns only the first area if multiple exist.

property turf_path: TypePath

Returns the path of the tile’s turf. Returns only the first area if multiple exist.

convert() → Any

Convert the tile definition to a Python data structure.

The result of convert is completely disassociated from the map tile definition, and modifying it will have no effect on the original tile.

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

Return the indexes of the prefabs prefixed with the given path prefix. If exact is True, then the prefab path must match exactly.

only(prefix: Any, exact: bool = False) → Any

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.

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) → TypePath

Return the path of the prefab at index.

prefab_vars(index: int) → list[str]

Return the list of variable names on the prefab at index.

prefab_var(index: int, name: str) → Any

Return the value of the property name on the prefab at index.

Raises an error if the property does not exist. For a method that returns a default if the property does not exist, see get_prefab_var.

get_prefab_var(index: int, name: str, default: Any | None = None) → Any

Returns the value of the property name on the prefab at index. If the property does not exist, return default.

Modifying Prefab Data

set_prefab_var(atom_index: int, name: str, val: Any) → None

Set the value of the variable name to val at index.

set_path(index: int, path: Any) → None

Set the path of the prefab at index to path.

add_path(index: int, entry: Any) → None

Add a prefab with the given path at index.

del_prefab(index: int) → None

Deletes the prefab at index.

del_prefab_var(index: int, name: str) → None