World > TiledWorld

World > TiledWorld#

API Reference#

class miniworlds.worlds.tiled_world.tiled_world.TiledWorld(x=20, y=16, tile_size=40, empty=False)[source]#

Grid-based world where actors are placed on tiles.

A TiledWorld uses tile coordinates instead of pixel coordinates for actor positions. Actors can also be placed on tile corners or edges.

Examples

Create a small grid world:

    from miniworlds import TiledWorld, Actor

    world = TiledWorld(6, 3)
    player = Actor((1, 1))
    player.fill_color = (255, 255, 255)

    @player.register
    def on_key_down_right(self):
        self.move_in_direction("right")

    world.run()

__init__(x=20, y=16, tile_size=40, empty=False)[source]#

Create a tiled world.

Parameters:

x – Number of columns.
y – Number of rows.
tile_size – Tile size in pixels.
empty – If True, tiles, edges, and corners are not created automatically.

Examples

world = TiledWorld(8, 6)
empty_world = TiledWorld(8, 6, empty=True)

add_corner_to_world(position, direction)[source]#

Create and register a corner.

Existing corners are merged when multiple tiles share the same corner.

Parameters:

position – Base tile position as (column, row).
direction – Corner direction key, for example “nw”.

Returns:

The registered corner object.

Examples

corner = world.add_corner_to_world((2, 3), "nw")

add_edge_to_world(position, direction)[source]#

Create and register an edge.

Existing edges are merged when neighboring tiles describe the same edge.

Parameters:

position – Base tile position as (column, row).
direction – Edge direction key, for example “n” or “w”.

Returns:

The registered edge object.

Examples

edge = world.add_edge_to_world((2, 3), "w")

add_tile_to_world(position)[source]#

Creates and registers a tile at a world grid position.

Parameters:: position – Tile position as (column, row).
Returns:: The created tile instance.

Examples

tile = world.add_tile_to_world((2, 3))

borders(value)[source]#

Return borders touched by a position or rectangle.

Return type:: list
Parameters:: value – Position or rectangle to check.
Returns:: List of border names such as “left” or “top”.

Examples

borders = world.borders(actor.position)

clear_tiles()[source]#

Remove all tiles, corners, and edges.

Use empty=True in the constructor when you want to build all tiles manually from the start.

Examples

world = TiledWorld(8, 8, empty=True)
world.add_tile_to_world((0, 0))

world.clear_tiles()
world.add_tile_to_world((1, 1))

property columns: int#

Width of the visible world area in pixels.

Examples

world.columns = 640

Type:: int

detect_actor_at_position(position)[source]#

Return the first actor at a tile position.

Parameters:: position – Tile position as (column, row).
Returns:: The first actor at that position, or None.

Examples

actor = world.detect_actor_at_position((2, 3))

detect_actors(position)[source]#

Return all actors at a world position.

Return type:: List[Actor]
Parameters:: position – World position as (x, y).
Returns:: Actors found at the position.

Examples

actors = world.detect_actors(player.position)
for actor in actors:
    if isinstance(actor, Coin):
        actor.remove()

detect_actors_at_position(position)[source]#

Return all actors at a tile position.

Parameters:: position – Tile position as (column, row).
Returns:: Actors located at that position.

Examples

actors = world.detect_actors_at_position((2, 3))

dialog#

draw_on_image(image, position)[source]#

Draw an image onto the tiled world background.

Parameters:

image – The image/surface to draw.
position – Tile position as (column, row).

Examples

world.draw_on_image(surface, (2, 3))

get_actors_from_pixel(position)[source]#

Return all actors under a screen pixel.

Return type:: List[Actor]
Parameters:: pixel – Screen pixel as (x, y).
Returns:: Actors whose screen rectangle overlaps the pixel.

Examples

@world.register
def on_mouse_left(self, position):
    for actor in self.get_actors_from_pixel(position):
        actor.hide()

get_corner(position, direction=None)[source]#

Return a corner by corner position or tile position plus direction.

Parameters:

position – Corner position, or tile position when direction is set.
direction – Optional corner direction, for example “nw”.

Returns:

The matching corner.

Raises:

CornerNotFoundError – If no corner exists at the resolved position.

Examples

corner = world.get_corner(actor.position)
corner = world.get_corner((3, 1), "nw")

get_corner_points()[source]#

Return type:: Dict[Tuple, Tuple[float, float]]

get_edge(position, direction=None)[source]#

Return an edge by edge position or tile position plus direction.

Parameters:

position – Edge position, or tile position when direction is set.
direction – Optional edge direction, for example “n” or “w”.

Returns:

The matching edge.

Examples

edge = world.get_edge(actor.position)
edge = world.get_edge((5, 1), "w")

get_edge_points()[source]#

Return type:: Dict[Tuple, Tuple[float, float]]

get_from_pixel(position)[source]#

Return the tile position for a screen pixel.

Parameters:: position – Pixel position as (x, y).
Returns:: Tile position, or None if the pixel is outside the camera view.

Examples

tile_position = world.get_from_pixel((80, 120))

get_tile(position)[source]#

Return the tile at a tile position.

Parameters:: position – Tile position as (column, row).
Returns:: The tile at the position.
Raises:: TileNotFoundError – If no tile exists at the position.

Examples

tile = world.get_tile(actor.position)
tile = world.get_tile((1, 1))

if tile.get_actors():
    print("Tile is occupied")

get_tile_from_pixel(position)[source]#

Return the tile under a screen pixel.

Parameters:: position – Pixel position as (x, y).
Returns:: Tile under the pixel.

Examples

tile = world.get_tile_from_pixel((80, 120))

property grid#

Whether to display the grid overlay.

Examples

world.grid = True

Type:: bool

is_corner(position)[source]#

Return whether a position is a corner position.

Examples

if world.is_corner(actor.position):
    actor.hide()

is_edge(position)[source]#

Return whether a position is an edge position.

Examples

if world.is_edge(actor.position):
    actor.hide()

is_tile(position)[source]#

Return whether a position is a tile position.

Examples

if world.is_tile((1, 1)):
    tile = world.get_tile((1, 1))

property rows: int#

Height of the visible world area in pixels.

Examples

world.rows = 480

Type:: int

set_columns(value)[source]#

Set the visible world width in pixels.

Parameters:: value – New width in pixels.

Examples

world.set_columns(640)

set_rows(value)[source]#

Set the visible world height in pixels.

Parameters:: value – New height in pixels.

Examples

world.set_rows(480)

set_tile_size(value)[source]#

Set the tile size in pixels.

Parameters:: value – New tile size in pixels.

Examples

world.set_tile_size(32)

property tile_size: int#

Size of one tile in pixels.

Examples

world.tile_size = 32

Type:: int

to_pixel(position, size=(0, 0), origin=(0, 0))[source]#

Convert a tile position to pixel coordinates.

Parameters:

position – Tile position as (column, row).
size – Reserved for compatibility.
origin – Pixel offset added to the converted position.

Returns:

Pixel position as (x, y).

Examples

pixel = world.to_pixel((2, 3))

World > TiledWorld

Contents

World > TiledWorld#

API Reference#