Read and modify .bytes files of the Refract Studios game Distance

distance, game, bytes, file, level, map, read, edit, modify, distance game bytes file level map read edit modify
pip install distanceutils==0.5.1



Read and modify .bytes files of the Refract Studios game Distance.


All modules and utilities are provided by the package distanceutils. For example, using pip:

$ pip install --user numpy
$ pip install --user distanceutils

Due to a problem with another dependency (numpy-quaternion), numpy needs to be installed first with a separate command.

Basic Usage

The core of this project can be imported with the distance module. With this module, .bytes files written by the game can be read, modified and written back to a file.

Reading a file is as easy as importing the module and passing a file name to the right class or a prober. Files can be written back to a file with modifications:

>>> from distance import Level
>>> level = Level("my_level.bytes")
>>> level.settings.name
'My Level'
>>> level.layers[0].objects[-1].type
>>> level.settings.name = 'My changed level'
>>> level.write("my_changed_level.bytes")

For an advanced introduction, see General Usage.

For more example usages, see the scripts provided with the distance_scripts module.

For a complete list of provided classes, run the following shell command:

python -m distance --list-classes

For objects that are missing here, base classes are used, so these objects can be written back to a file without changes.


The following executable scripts are included with this package:

dst-bytes - Print various data of given .bytes files.

dst-mkcustomobject - Extract a CustomObject from a level or from another CustomObject.

dst-filterlevel - Apply filters to a level or CustomObject. For a list of filters, see filters.

dst-objtobytes - Generate a CustomObject from a wavefront .obj 3D model file.

dst-teletodot - Take a level .bytes file and generate a Graphviz dot document of teleporter connections.

dst-mklevelinfos - Generate the cache database from WorkshopLevelInfos.bytes.

dst-querymaps - Query the cache database.