Avulto

Avulto is a Python library for working in the BYOND environment. Its goal is to provide a straightforward Python API which leverages the SpacemanDMM and potentially other community libraries.

Its primary use cases are to easily

read and modify map files
parse and read icon files
read the source tree and provide reflection data.

Usage

Avulto is available as a release on PyPI. See the Development section below for directions on using the library locally.

Avulto's API is documented in full in its stub file, but the most important parts of its API are below.

`Path`

Path wraps type paths and provides parent_of(other, strict=False) and child_of(other, strict=False) for comparing paths. When strict, the current path does not count as a parent or child of itself.It also supports the division operator for easy path suffixing.

from avulto import Path as p

>>> p('/obj/machinery').parent_of('/obj/machinery/oven')
True

>>> p('/turf').child_of('/turf', strict=True)
False

>>> p('/obj/machinery') / 'microwave'
/obj/machinery/microwave

`DMM`

The DMM class allows parsing and manipulation of map files.

Method	Description
`from_file(filename)`	Creates a `DMM` from the given `filename`.
`save_to(filename)`	Saves the `DMM` to the given `filename`.
`coords()`	Return an iterator over all possible 3D coordinates.
`tiles()`	Return an iterator over all unique `Tile`s on the map.
`tiledef(x, y, z)`	Returns the `Tile` at the given coordinates.
`extents`	The maximum size of the map's dimensions.

Tile objects returned from DMM.tiles() and DMM.tiledef(x, y, z) have the following API:

Method	Description
`area_path()`	Returns the tile's area.
`turf_path()`	Returns the tile's turf.
`convert()`	Provide a Python representation of all tile prefabs.

Inspecting and manipulating prefabs on a tile is performed on the prefab's index:

Method	Description
`find(prefix)`	Return the indexes of all the prefabs on the tile with the given `prefix`.
`prefab_path(index)`	Return the path of the prefab at `index`.
`prefab_vars(index)`	Return the list of var names at `index`.
`prefab_var(index, name)`	Return the value of the var `name` at `index`.
`set_prefab_var(index, name, val)`	Set the value of the var `name` at `index` to `val`.
`set_path(index, path)`	Set the path of the prefab at `index` to `path`.
`add_path(index, path)`	Add a prefab with the given `path` at `index`.
`del_prefab(index)`	Deletes the prefab at `index`.
`del_prefab_var(index, name)`	Deletes the var `name` from the prefab at `index`.

Note that the mutative functions above currently apply to the preset, not the individual tile. Future releases will hopefully provide a way to do both.

`DME`

The DME class allows parsing DM object code:

Method	Description
`from_file(filename)`	Creates a `DME` from the given `.dme` file.
`paths_prefixed(prefix)`	Returns a list of paths with the given `prefix`, including `prefix` if it exists.
`typedecl(path)`	Returns a `TypeDecl` of the object `path`.

TypeDecl objects allow variable inspection:

Method	Description
`procnames()`	Returns a list of proc names for the type declaration.
`varnames()`	Returns a list of variable names for the type declaration.
`value(name)`	Return a Python representation of the variable `name`.

DMI

The DMI class allows parsing icon files.

Method	Description
`from_file(filename)`	Creates a `DME` from the given `.dme` file.
`state_names()`	Return a list of strings containing all state names in the file.
`state(name)`	Returns the `IconState` with the given `name`.
`data_rgba8(rect)`	Returns the image data for the given rect in RGBA8 bytes.

IconState objects allow icon state inspection:

Method	Description
`name()`	The icon state name.
`delays()`	The delay per frame, in ticks.
`dirs()`	The directions available in the icon state.
`frames()`	The number of frames in the state.
`movement()`	Whether the icon state is a movement state.
`rewind()`	Whether the state rewinds on animation.
`rect(dir, frame)`	The Rect of the given frame and direction in the file.

Using Pillow, the image data for a given icon can quickly be turned into an Image object and easily manipulated:

>>> from avulto import DMI, Dir
>>> from PIL import Image
>>> dmi = DMI.from_file("/SS13/icons/objects/weapons.dmi")
>>> pistol = dmi.state("pistol")
>>> pistol_rect = pistol.rect(Dir.SOUTH, frame=0)
>>> pistol_data = dmi.data_rgba8(pistol_rect)
>>> image = Image.frombytes("RGBA", size=(pistol_rect.width, pistol_rect.height), data=pistol_data)

Development

Avulto is written in Rust and implemented using PyO3, and uses maturin for development. To build and install locally:

$ python -m maturin build; python -m pip install .
$ python -m pytest

Planned Development

More DMI icon data.
Getting image data directly through SpacemanDMM.
Better errors and consistent API surface area.
More reflection data, including method names.

License

Avulto is licensed under the GPL. See LICENSE for more information.

Acknowledgements

Portions of Avulto are originally based on SpacemanDMM, copyright Tad Hardesty and licensed under the GPL.

Portions of Avulto are originally based on StrongDMM, copyright SpaiR and licensed under the GPL.

warriorstar-orion / avulto