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)

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

Return type:

int

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.

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.

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