xSGE Tiled Library
******************


Contents
^^^^^^^^

* xSGE Tiled Library

  * xsge_tiled Classes

  * xsge_tiled Functions

xSGE is a collection of higher-level extensions for the SGE which
enhance the core functionality in an implementation-independent way.
Like the SGE itself, they are distribted under the terms of the GNU
Lesser General Public License.

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, *, checks_collisions=False, tangible=False, **kwargs)

   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, *, visible=False, **kwargs)

   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, *, visible=False, **kwargs)

   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, *, visible=True, collision_ellipse=True, **kwargs)

   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:

     * Point objects default to "Point".

     * Rectangle objects default to "Rectangle".

     * Ellipse objects default to "Ellipse".

     * Polygon objects default to "Polygon".

     * Polyline objects default to "Polyline".

     * Tile objects default to "Decoration".

   * 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.

   Note:

     Only orthogonal, staggered, and hexagonal maps are supported. For
     best results, the following conditions should be adhered to:

     * Stagger index should be set to "odd".

     * For non-hexagonal staggered maps, stagger axis should be set to
       "y". (Does not apply to hexagonal maps; in the case of
       hexagonal maps, both "x" and "y" will work just as well.)

     Maps which do not adhere to these conditions will still render
     correctly, but adhering to these conditions will allow
     "sge.gfx.TileGrid" to be used, which allows for better
     performance.

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.

   * A dictionary linkint Tiled GID keys to objectalignment values
     specified in Tiled.

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

   Warning:

     Due to its nature, this function's return value is subject to
     being extended with additional tuple values without notice.

xsge_tiled.t_parse_layer(layer, tilemap, tmdir, tile_cls, tile_sprites, tile_kwargs, tile_objectalignment, types, z, *, tintcolor=None)

   Parse a layer and return a tuple containing three 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.

   Warning:

     Due to its nature, this function's return value is subject to
     being extended with additional tuple values without notice.

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

   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.
