gale.tilemap.tilemap module

This file contains the implementation of the classes Tileset (one tileset image sliced into tiles, occupying a range of global tile ids) and TileMap (a stack of named tile layers sharing tileset(s), rendered with gale.camera culling built in).

Author: Alejandro Mujica (aledrums@gmail.com)

gale.tilemap.tilemap.decode_gid(raw_gid)

Parameters:

raw_gid (int) – A tile id as read straight from a Tiled layer’s data – a plain gid, or one with its top 3 bits set to flag a flipped/rotated tile.

Returns:

(gid, flip_horizontal, flip_vertical, flip_diagonal) – raw_gid with the flip flags cleared, and each flag as a bool. All False and gid == raw_gid for a tile that isn’t flipped/rotated.

Return type:

Tuple[int, bool, bool, bool]

class gale.tilemap.tilemap.Tileset(image, tile_width, tile_height, first_gid=1, margin=0, spacing=0, tile_properties=None)

Bases: object

One tileset image, sliced into tiles, occupying a contiguous range of global tile ids (gids) starting at first_gid — the same model Tiled (https://www.mapeditor.org/) uses to let a single map reference more than one tileset image.

Usage example:

tileset = Tileset(pygame.image.load(“tiles.png”), 16, 16, first_gid=1)

Parameters:

• image (Surface)

• tile_width (int)

• tile_height (int)

• first_gid (int)

• margin (int)

• spacing (int)

• tile_properties (Dict[int, Dict[str, Any]] | None)

property tile_count: int

property last_gid: int

contains(gid)

Parameters:

gid (int) – A global tile id.

Returns:

Whether gid falls within this tileset’s range.

Return type:

bool

rect_for(gid)

Parameters:

gid (int) – A global tile id known to be within this tileset’s range (see contains).

Returns:

The area of this tileset’s image that gid’s tile occupies.

Return type:

Rect

properties_for(gid)

Parameters:

gid (int) – A global tile id known to be within this tileset’s range (see contains).

Returns:

gid’s custom properties, or {} if it has none.

Return type:

Dict[str, Any]

class gale.tilemap.tilemap.TileMap(tile_width, tile_height, cols, rows)

Bases: object

A grid of tile layers (each a rows x cols grid of gids, 0 meaning “empty”) sharing one coordinate system, plus the tileset(s) that render them and any object layers (spawn points, triggers…) carried along for the game to interpret however it wants.

Layers render in the order they were added (the first one is the back-most), the same top-to-bottom-is-back-to-front convention gale.ui.Container uses for widgets.

Usage example:

tilemap = TileMap(tile_width=16, tile_height=16, cols=50, rows=12) tilemap.add_tileset(Tileset(tiles_image, 16, 16, first_gid=1)) ground = tilemap.add_layer(“ground”) ground[5][10] = 1 # place tile gid 1 at row 5, col 10

# Every frame: tilemap.render(surface, camera)

Typically built by load_tiled_map rather than by hand — see docs/examples/tilemap.rst.

Parameters:

• tile_width (int)

• tile_height (int)

• cols (int)

• rows (int)

property pixel_width: int

property pixel_height: int

add_tileset(tileset)

Parameters:

tileset (Tileset) – A Tileset to make available to this map’s layers. Order doesn’t matter — tileset_for_gid resolves the right one for a given gid regardless of add order.

Return type:

None

add_layer(name, grid=None)

Parameters:

• name (str) – This layer’s name, used to refer back to it (get_layer, get_gid, collision helpers…).

• grid (List[List[int]] | None) – The layer’s initial rows x cols gids. The default value is None, filling a new all-empty (every gid 0) grid.

Returns:

The layer’s grid (also reachable later through get_layer), so it can be filled in directly.

Return type:

List[List[int]]

layer_names()

Returns:

Every tile layer’s name, in render order (back to front).

Return type:

List[str]

get_layer(name)

Parameters:

name (str) – A layer added through add_layer.

Returns:

That layer’s rows x cols grid of gids.

Return type:

List[List[int]]

get_gid(layer_name, row, col)

Parameters:

• layer_name (str) – A layer added through add_layer.

• row (int) – A tile row.

• col (int) – A tile column.

Returns:

The gid at that cell (0 means empty), with any Tiled flip/rotation flags (see decode_gid) already cleared – use get_flip to read those.

Return type:

int

get_flip(layer_name, row, col)

Parameters:

• layer_name (str) – A layer added through add_layer.

• row (int) – A tile row.

• col (int) – A tile column.

Returns:

(flip_horizontal, flip_vertical, flip_diagonal) for the tile at that cell, decoded from the raw gid Tiled stored there. All False for a tile that isn’t flipped/rotated.

Return type:

Tuple[bool, bool, bool]

set_gid(layer_name, row, col, gid)

Parameters:

• layer_name (str) – A layer added through add_layer.

• row (int) – A tile row.

• col (int) – A tile column.

• gid (int) – The gid to place there (0 to clear it).

Return type:

None

in_bounds(row, col)

Returns:

Whether (row, col) falls inside this map’s rows x cols grid.

Parameters:

• row (int)

• col (int)

Return type:

bool

tile_at(x, y)

Parameters:

• x (float) – A world x position, in pixels.

• y (float) – A world y position, in pixels.

Returns:

The (row, col) of the tile containing that point (not clamped to this map’s bounds — check in_bounds if the point might fall outside it).

Return type:

Tuple[int, int]

position_of(row, col)

Parameters:

• row (int) – A tile row.

• col (int) – A tile column.

Returns:

The world pixel position of that cell’s top-left corner.

Return type:

Tuple[float, float]

tileset_for_gid(gid)

Parameters:

gid (int) – A global tile id (a raw one straight from Tiled, with its flip flags still set, works too – see decode_gid).

Returns:

Whichever added Tileset’s range gid falls in, or None (gid is 0/empty, or out of range of every tileset added so far).

Return type:

Tileset | None

properties_of_gid(gid)

Parameters:

gid (int) – A global tile id (a raw one straight from Tiled, with its flip flags still set, works too – see decode_gid).

Returns:

That tile’s custom properties (as set on the tile in Tiled’s tileset editor), or {} if it has none or gid is empty/unknown.

Return type:

Dict[str, Any]

render(surface, camera=None)

Parameters:

• surface (Surface) – The surface to draw every layer onto.

• camera (Any | None) – A gale.camera.Camera to translate/scale tiles through and cull to only the visible range. The default value is None, rendering the whole map at a 1:1 scale starting at (0, 0).

Return type:

None