xSGE Tiled Library

xSGE is a collection of extensions for the SGE licensed under the GNU General Public License. They are designed to give additional features to free/libre software games which aren't necessary, but are nice to have.

xSGE extensions are not dependent on any particular SGE implementation. They should work with any implementation that follows the specification.

This extension provides support for loading the JSON format of the Tiled Map Editor. This allows you to use Tiled to edit your game's world (e.g. levels), rather than building a level editor yourself.

To load a tile map, simply use load(). See the documentation for this function for more information.

xsge_tiled Classes

class xsge_tiled.Decoration(x, y, z=0, sprite=None, visible=True, active=False, checks_collisions=False, tangible=False, bbox_x=None, bbox_y=None, bbox_width=None, bbox_height=None, regulate_origin=False, collision_ellipse=False, collision_precise=False, xvelocity=0, yvelocity=0, xacceleration=0, yacceleration=0, xdeceleration=0, ydeceleration=0, image_index=0, image_origin_x=None, image_origin_y=None, image_fps=None, image_xscale=1, image_yscale=1, image_rotation=0, image_alpha=255, image_blend=None, image_blend_mode=None)

Default class for tiles and image layers. Identical to sge.dsp.Object, except that it is intangible and doesn't check for collisions by default.

class xsge_tiled.Point(x, y, z=0, sprite=None, visible=False, active=True, checks_collisions=True, tangible=True, bbox_x=None, bbox_y=None, bbox_width=None, bbox_height=None, regulate_origin=False, collision_ellipse=False, collision_precise=False, xvelocity=0, yvelocity=0, xacceleration=0, yacceleration=0, xdeceleration=0, ydeceleration=0, image_index=0, image_origin_x=None, image_origin_y=None, image_fps=None, image_xscale=1, image_yscale=1, image_rotation=0, image_alpha=255, image_blend=None, image_blend_mode=None)

Default class for point objects. Identical to sge.dsp.Object, except that it is invisible by default.

class xsge_tiled.Rectangle(x, y, z=0, sprite=None, visible=False, active=True, checks_collisions=True, tangible=True, bbox_x=None, bbox_y=None, bbox_width=None, bbox_height=None, regulate_origin=False, collision_ellipse=False, collision_precise=False, xvelocity=0, yvelocity=0, xacceleration=0, yacceleration=0, xdeceleration=0, ydeceleration=0, image_index=0, image_origin_x=None, image_origin_y=None, image_fps=None, image_xscale=1, image_yscale=1, image_rotation=0, image_alpha=255, image_blend=None, image_blend_mode=None)

Default class for rectangle objects. Identical to sge.dsp.Object, except that it is invisible by default.

class xsge_tiled.Ellipse(x, y, z=0, sprite=None, visible=True, active=True, checks_collisions=True, tangible=True, bbox_x=None, bbox_y=None, bbox_width=None, bbox_height=None, regulate_origin=False, collision_ellipse=True, collision_precise=False, xvelocity=0, yvelocity=0, xacceleration=0, yacceleration=0, xdeceleration=0, ydeceleration=0, image_index=0, image_origin_x=None, image_origin_y=None, image_fps=None, image_xscale=1, image_yscale=1, image_rotation=0, image_alpha=255, image_blend=None, image_blend_mode=None)

Default class for ellipse objects. Identical to sge.dsp.Object, except that it is invisible and uses ellipse collision detection by default.

class xsge_tiled.Polygon(x, y, points=(), z=0, visible=False, tangible=False, **kwargs)

Default class for polygon objects. Identical to xsge_path.Path.

class xsge_tiled.Polyline(x, y, points=(), z=0, visible=False, tangible=False, **kwargs)

Default class for polyline objects. Identical to xsge_path.Path.

xsge_tiled Functions

xsge_tiled.load(fname, cls=<class 'sge.dsp.Room'>, types=None, z=0)

Load JSON tilemap fname and return a room of the class cls.

The way the map generates the room, in general, is to convert all tiles, objects, and image layers into sge.dsp.Object objects. As a special exception, the object layer with the name "views" defines the views in the room; these objects are converted into sge.dsp.View objects.

Objects are given Z-axis positions based on the ordering of the layers in the map file: z is the Z-axis position of the first layer, and each subsequent layer's Z-axis position is the Z-axis position of the previous layer plus one.

Except for views, all tiles, objects, and image layers can be defined to be converted into any class derived from sge.dsp.Object via the types argument, which should be a dictionary matching strings to corresponding sge.dsp.Object classes, or None, which is equivalent to {}. Classes are determined in the following ways:

  • Tiles are converted to the class connected to, in order of preference, the name of the tileset, the type of the tileset, or the name of the tile layer. If none of these values are valid keys in types, Decoration is used.
  • Objects are converted to the class connected to, in order of preference, the name of the object, the type of the object, the appropriate class for the respective tile if applicable (see above), or the name of the object group. If none of these strings are valid keys in types, the class used depends on what kind of object it is:
  • Image layers are converted to the class connected to the image layer's name. If the image layer's name is not a valid key in types, Decoration is used.

Property lists are passed to objects as keyword arguments in the following ways:

  • Tiles have their properties, the properties of their tilesets, and the properties of their layers applied to them. Tileset properties override layer properties, and tile properties override tileset properties.
  • Tile objects have their properties, the properties of their tiles, the properties of their tiles' tilesets, and the properties of their object groups applied to them. Object properties override tile properties, tile properties override tileset properties, and tileset properties override object group properties.
  • Other objects have their properties and the properties of their object groups applied to them. Object properties override object group properties.
  • Image layers have their properties applied to them.

Note

Currently zstd compression is not supported. Support for zstd will be added later either when it makes it into the Pyhton Standard Library or, if that doesn't happen, when it's clear what zstd library to use.

xsge_tiled.t_get_tilesets(tilemap, tmdir, types)

Parse tilesets from loaded JSON data in tilemap. tmdir indicates the directory that the data from tilemap is from. Returns a tuple containing the following:

  • A dictionary linking Tiled GID keys to classes found in types.
  • A dictionary linking Tiled GID keys to SGE sprites.
  • A dictionary linking Tiled GID keys to keyword argument dictionaries based on the properties of the tileset and tiles.

This is a low-level function used internally by this library; you don't typically need to use it.

xsge_tiled.t_parse_layer(layer, tilemap, tmdir, tile_cls, tile_sprites, tile_kwargs, types, z)

Parse a layer and return a tuple containing two values:

  • A list of objects retrieved by the layer.
  • A list of views retrieved by the layer.
  • The next z index to be used by another layer.

This is a low-level function used internally by this library; you don't typically need to use it.

xsge_tiled.t_parse_tilechunk(chunk, tilemap, layer, tile_cls, tile_sprites, tile_kwargs, default_cls, default_kwargs, types, z)

Parse a chunk of a layer and return a list of objects generated.

This is a low-level function used internally by this library; you don't typically need to use it.

xsge_tiled.t_get_properties(properties)

Convert Tiled properties list properties into a dictionary of keyword arguments and return said dictionary.

This is a low-level function used internally by this library; you don't typically need to use it.

xsge_tiled.t_gid_parse(gid)

Parse the GID given and return a tuple with the following values:

  • The real GID without bitwise flags.
  • Whether or not the tile is horizontally flipped.
  • Whether or not the tile is vertically flipped.
  • Whether or not the tile is "diagonally" flipped.

This is a low-level function used internally by this library; you don't typically need to use it.

xsge_tiled.t_get_color(value)

Return a sge.gfx.Color object corresponding to s, based on Tiled's color formatting.

This is a low-level function used internally by this library; you don't typically need to use it.

xsge_tiled.t_data_decode(data, encoding, compression)

Decode encoded data and return a list of integers it represents.

Arguments:

  • data -- The data to decode.
  • encoding -- The encoding of the data. Can be "base64" or "csv".
  • compression -- The compression method used. Valid compression methods are "gzip" and "zlib". Set to None for no compression.

This is a low-level function used internally by this library; you don't typically need to use it.