Universal Level Formats documentation — Universal Level Formats 1.0 documentation

# Universal Level Formats documentation

Contents

- Universal Level Formats documentation
  - Level Format Classes
    - ulvl.JSL
      - ulvl.JSL Methods
    - ulvl.ASCL
      - ulvl.ASCL Methods
    - ulvl.ULX
      - ulvl.ULX Methods
    - ulvl.TMX
      - ulvl.TMX Methods
  - Helper Classes
  - Indices and tables

This library reads and writes universal level formats. These level formats are generic enough to be used by any 2-D game. Their purpose is to unify level editing under a simple, universal format.

## Level Format Classes

These classes load and save levels for their respective formats. `ulvl.JSL` is generally the recommended format, but alternatives are offered as well.

### ulvl.JSL

class `ulvl.` `JSL`

  This class loads, stores, and saves JavaScript Level (JSL) files. This format is based on JSON and generally has one of the following extensions: ".jsl", ".json".

  A JSL file contains a top-level object with the following keys:

  - `"meta"`: A value of any type indicating the layer's meta variable.
  - `"objects"`: An object with the level's object types as keys and arrays as values. The array lists the meta variables of all objects of the respective type (`null` for objects with no meta variable defined).
  - `"layers"`: An array of objects indicating tile layers, with each of these objects containing the following keys:
    - `"type"`: A value of any type indicating the type of the layer.
    - `"columns"`: An integer indicating the number of columns in the tile layer.
    - `"tiles"`: A zlib-compressed, base64-encoded string encoding the tile IDs as data.
    - `"meta"`: A value of any type indicating the layer's meta variable.
  `meta`

    Meta variable for the level as a whole. Can be any value.

  `objects`

    A list of `LevelObject` objects representing objects of the level.

  `layers`

    A list oj `TileLayer` objects representing the tile layers of the level.

#### ulvl.JSL Methods

classmethod `JSL.` `load`(f)

  Load the indicated file and return a `JSL` object.

`JSL.` `save`(f)

  Save the object to the indicated file.

### ulvl.ASCL

class `ulvl.` `ASCL`

  This class loads, stores, and saves ASCII Level (ASCL) files. This format is based on a grid of plain text characters and generally has one of the following extensions: ".ascl", ".asc", ".txt".

  An ASCL file contains two main components: the meta variable definitions and the level object grid.

  Meta variables are defined simply at the top of the file: each line indicates the value of a different meta variable, always a string. Any number of meta variables can be defined.

  Everything after the first blank line in the ASCL file is considered to be part of the tile layer. Here, ASCII characters are used to represent the tiles found in `tiles`.

  `meta`

    A list of the level's meta variables.

    Note

    The meta variables can be any value, but when the ASCL is saved, all meta variables will be automatically converted to strings.

  `layer`

    A `TileLayer` object indicating the tiles of the level.

    Note

    Due to the nature of the format, the layer type and meta variable of the layer are ignored and not preserved when saving.

#### ulvl.ASCL Methods

classmethod `ASCL.` `load`(f)

  Load the indicated file and return an `ASCL` object.

`ASCL.` `save`(f)

  Save the object to the indicated file.

### ulvl.ULX

class `ulvl.` `ULX`

  This class loads, stores, and saves Universal Level XML (ULX) files. This format is based on XML and generally has one of the following extensions: ".ulx", ".xml".

  A ULX file contains a root tree with the name "level" containing the following children:

  - `meta`: Contains one element for each of the level's meta variables. Each element's tag indicates the name of the meta variable, while its text indicates the value.
  - `objects`: Contains `object` elements. Each `object` element has the following attributes:
    - `"type"`: The object's type.
    - `"meta"`: The object's meta variable.
  - `layers`: Contains `layer` elements. Each `layer` element contains text indicating the layer's tiles as zlib-compressed base64-encoded text, and the following attributes:
    - `"type"`: The layer's type.
    - `"columns"`: The number of columns in the tile layer.
    - ``"meta": The layer's meta variable.

  Note

  Types and meta variables of all kinds can be any value, but due to the nature of XML, all types and meta variables are converted to strings when the ULX is saved. A value of `None` leads to the ULX omitting the meta variable.

  `meta`

    A dictionary of all of the level's meta variables.

  `objects`

    A list of objects in the level as `LevelObject` objects.

  `layers`

    A list oj `TileLayer` objects representing the tile layers of the level.

#### ulvl.ULX Methods

classmethod `ULX.` `load`(f)

  Load the indicated file and return a `ULX` object.

`ULX.` `save`(fname)

  Save the object to the indicated file name.

### ulvl.TMX

class `ulvl.` `TMX`

  A class for reading (but not writing) TMX files created by the Tiled Map Editor in a generic manner.

  Only map meta-data, basic tile layers (but not group layers or image layers), and object groups are captured. Captured meta-data is converted to numeric form whenever it is supposed to be. All other values are left as strings.

  Saving in this format is not supported due to its complexity.

  See the TMX format specification for more information on the format itself:

  https://doc.mapeditor.org/en/stable/reference/tmx-map-format/

  `meta`

    A dictionary of level meta variables obtained from the TMX. The following meta variables are captured if available:

    - "orientation" (from the <map> tag)
    - "dictionary" (from the <map> tag)
    - "width" (from the <map> tag)
    - "height" (from the <map> tag)
    - "tilewidth" (from the <map> tag)
    - "tileheight" (from the <map> tag)
    - "backgroundcolor" (from the <map> tag)
    - All custom map properties
  `objects`

    A list of objects in the level as `LevelObject` objects. These are taken from the TMX object tags. Layering of objects is not preserved. Each `LevelObject` object's type becomes, in order of preference: the name of the TMX object, the type of the TMX object, or the name of the TMX object group. Each `LevelObject` object's meta variable is set as a dictionary of values obtained from the TMX. The following meta variables are captured if available:

    - "color" (from the <objectgroup> tag)
    - "opacity" (from the <objectgroup> tag)
    - "offsetx" (from the <objectgroup> tag)
    - "offsety" (from the <objectgroup> tag)
    - "x" (from the <object> tag)
    - "y" (from the <object> tag)
    - "width" (from the <object> tag)
    - "height" (from the <object> tag)
    - "rotation" (from the <object> tag)
    - "gid" (from the <object> tag)
    - "visible" (from the <object> tag)
    - All custom object properties

    Note

    Remember that a tile object's origin is in the bottom-center, unlike shape-based objects whose origin is in the top-left. You can find out if an object is a tile object by checking the respective level object's `meta["gid"]` after loading. If this value is not `None`, the object is a tile object.

  `layers`

    A list oj `TileLayer` objects representing the tile layers of the level. These are taken from the TMX layer tags. Tile flipping and rotation are not supported; attempts to flip or rotate tiles will simply be interpreted as completely different tiles.

    Tile IDs are also localized so that a tile ID of 1 is the first tile of the tileset, 2 is the second, and so on. For means of simplification and consistency, only one tileset can be used per layer and all tile global IDs will be localized based on the tile IDs contained within.

    Each `TileLayer` object's type becomes the name of the TMX layer. Each `TileLayer` object's meta variable is set as a dictionary of values obtained from the TMX. The following meta variables are captured if available:

    - "width" (from the <layer> tag)
    - "height" (from the <layer> tag)
    - "opacity" (from the <layer> tag)
    - "visible" (from the <layer> tag)
    - "offsetx" (from the <layer> tag)
    - "offsety" (from the <layer> tag)
    - All custom layer properties

#### ulvl.TMX Methods

classmethod `TMX.` `load`(f)

  Load the indicated file and return a `TMX` object.

## Helper Classes

These classes are helpers used by the level format classes to store data.

class `ulvl.` `TileLayer`(type_, columns, tiles, meta=None)

  A layer of tiles. Tiles are simple position-based objects with no special individual options, generally useful for large numbers of basic objects.

  `type`

    The type of tile layer this is. Can be any arbitrary value.

  `columns`

    The number of columns in each tile row.

  `tiles`

    A list of integers indicating the tiles of the layer. A value of `0` indicates no tile. Any higher value indicates the tile ID of the tile. Tile IDs are arbitrary; you decide what each tile ID means for the game.

  `meta`

    Meta variable for the tile layer as a whole. Can be any value. Set to `None` for no value.

class `ulvl.` `LevelObject`(type_, meta=None)

  A generic level object. Level objects are similar to tiles, but positioning is arbitrary and they can have meta information assigned to them.

  `type`

    The type of object this is. Can be any arbitrary value.

  `meta`

    Meta variable of the object. The meaning of this value is completely arbitrary; use it for any variations (position, size, etc) level objects have, in whatever way is most appropriate for the game. Set to `None` for no value.

## Indices and tables

- Index
- Module Index
- Search Page